Skip to content

Commands

Every brainrc command and option. brainrc --help lists the commands and brainrc <command> --help shows one command's options. From a clone, run python3 scripts/brainrc.py <command> instead. brainrc with no command runs status, and brainrc --version prints the version.

A test checks this page against the command's own help, so it lists every command and option there is.

Set up: init · import · new pack · Install: status · apply · update · install · uninstall · Check: check · audit · doctor · validate · tokens · Other: pin-mcp · migrate

brainrc init

First run: pick the tools to manage, adopt your existing instruction files, and choose how much to install. It writes harnesses.local.toml, packs.local.toml and brainrc.local.toml, and never runs apply (getting started).

Option Does
--yes, -y ask nothing: manage every installed tool and adopt every instruction file
--harness HARNESS manage exactly these tools (--harness claude,codex, or repeat it); asks nothing
--no-adopt leave your instruction files where they are
--profile minimal\|recommended\|full set the profile (configuration)
--starter minimal\|app\|infra set a starter profile instead: rules only; no infrastructure skills; everything
--import import this folder's CLAUDE.md, AGENTS.md, Cursor and Copilot files into the pack imported without asking
--dry-run print what init would do, write nothing

brainrc import

Turn instruction files you already have into a pack: one rule per section, in order (packs).

brainrc import ~/.claude/CLAUDE.md --name mine --enable
Option Does
PATH ... files or folders to import, in order
--to DIR where to write the pack (default $BRAINRC_HOME/imported/<name>)
--name NAME the pack's name (default imported)
--prefix PREFIX the prefix for its skills (default <name>-)
--format FORMAT read every PATH as this format, whatever its name
--force replace an earlier pack in that folder
--enable add the pack to packs.local.toml
--dry-run print the files it would write, write nothing

brainrc new pack

Start a pack of your own that validates on its first run: pack.toml, a README, an AGENTS.md for whoever edits it, a first rule, a facts skill, tripwires, tests, a CI workflow, a pre-commit config and a .gitignore (packs). In a terminal it asks for what you don't give it; otherwise it takes the defaults. A folder that holds only .git, such as a fresh clone, counts as empty. Then it checks the pack as validate --pack does.

brainrc new pack acme
brainrc validate --pack acme
Option Does
NAME the pack's name (asked for in a terminal)
--to DIR where to write it (default ./<name>)
--prefix PREFIX the prefix for its items (default <name>-, or <owner>- with --id)
--id OWNER/PACK the ID it is published under (naming)
--description TEXT one line on what the pack is for
--harness HARNESS the tools you'll edit it with: claude adds a CLAUDE.md, gemini a GEMINI.md, each pointing at AGENTS.md (default: every enabled tool)
--ticket none\|github\|jira\|local the ticket system Gatework uses for the pack's refs (default none)
--refs REF,... the ticket refs it handles, such as ACME-* (default: from the ticket system)
--host HOST with --ticket jira: the Jira site, such as acme.atlassian.net
--yes, -y ask nothing: take the defaults
--force replace an earlier pack in that folder; its .git stays
--enable add the pack to packs.local.toml
--dry-run print the files it would write, write nothing

brainrc status

Show what apply would change, for this machine and for the project you are in. Writes nothing. The words it prints are explained in getting started.

Option Does
--only HARNESS only these tools (--only claude,codex, or repeat it)
--repair also show the links apply --repair would fix

brainrc apply

Render rules, link items into each tool, and merge hooks and MCP servers into its settings. Then, in a repo with brainrc.toml, write the project's files. Keeps each git pack at its locked commit.

Option Does
--only HARNESS only these tools; the others are left exactly as they are
--repair also relink links left broken by moving a clone or upgrading brainrc
--yes, -y accept new hooks, MCP servers, tool grants and network domains from packs without asking. Without it, apply asks, and refuses where it can't ask (CI, a pipe)

brainrc update

Move git packs to what their ref points at now. It prints the commits and files that change, then runs apply and relocks. This is the only command that moves a pin (team setup).

Option Does
PACK ... the packs to move (default: every git pack)
--yes, -y accept new permissions without asking, as for apply

brainrc install

Without --frozen, the same as apply. With --frozen, install exactly what brainrc.lock records, or fail and write nothing. For CI and teammates (team setup).

Option Does
--frozen install exactly what the lock records
--scope user\|project which lock --frozen installs (default: the project's when there is one)
--force with --frozen in a project: overwrite files at the lock's paths that brainrc didn't write
--yes, -y as for apply; not with --frozen, where the lock is the approval

brainrc uninstall

Remove everything apply put into your tools: links, hooks, MCP servers, and the folders that leaves empty. Your own settings stay, and an instructions file init moved aside is put back.

Option Does
--dry-run print what would be removed, remove nothing
--purge also delete the settings home: local config, rendered files and fetched packs

brainrc check

Exit 1 when the packs or the repo's agent files differ from brainrc.lock, naming each difference. No network, writes nothing. Made for CI (team setup).

Option Does
--scope user\|project which lock to check (default: the project's when there is one)

brainrc audit

List every skill, agent, command, rule, hook and MCP server each tool loads from brainrc, with the pack it came from, the pack's commit and the item's hash. Then each pack's permissions and each MCP server's pinned tools. No network, writes nothing (guardrails).

Option Does
--json print it as JSON

brainrc doctor

Check this machine's install: stale rules, missing or broken links, packs not fetched, hooks that can't run, a plugin installed twice. Prints each problem with its fix and exits 1 if there is one. Changes nothing. No options.

brainrc validate

Check every source: frontmatter, links and references, pack names, collisions, requires_core, token budgets and tripwires. CI runs it on brainrc itself; pack authors run it with --pack (packs).

Option Does
--pack DIR check core plus this pack only, and run the pack's own tests
--fetch-defaults with --pack: check it against the default packs at the versions core pins, fetched into separate clones

brainrc tokens

Estimate the context cost of each skill, agent and command: what loads in every session and what loads on use. No options (packs).

brainrc pin-mcp

Start each stdio MCP server brainrc installs for Claude Code, list its tools, and on your yes record a hash of each one. A hook then warns at session start when a pinned tool changes (MCP servers).

Option Does
SERVER ... the servers to pin (default: every one)
--yes, -y approve new and changed tool definitions without asking

brainrc migrate

Move the old settings home from before the rename (~/.config/ai-config or $AICFG_HOME) to ~/.config/brainrc (or $BRAINRC_HOME), then run apply. Refuses a target that isn't empty (upgrading).

Option Does
--dry-run only print the move

Exit codes

0 on success. 1 when a command found a problem: a CONFLICT, a failed check, drift, or an error in a config file. 2 for a usage error, such as an unknown option.