CLI Reference

Global options

All commands support --help for usage information.

Flag	Description
`--format <toon\|json\|yaml\|md\|jsonl>`	Output format
`--filter-output <keys>`	Filter output by key paths (e.g. `foo,bar.baz,a[0,3]`)
`--verbose`	Show full output envelope
`--token-count`	Print token count of output instead of output
`--token-limit <n>`	Limit output to n tokens
`--token-offset <n>`	Skip first n tokens of output
`--schema`	Show JSON Schema for command
`--llms`, `--llms-full`	Print LLM-readable manifest
`--mcp`	Start as MCP stdio server
`--version`	Show version

init

Initialize brainjar: config, server, and optional seed content.

brainjar init [--default] [--backend claude|codex]

Flag	Description
`--default`	Seed starter soul, personas, and rules
`--backend`	Agent backend to target (default: `claude`)

status

Show active brain configuration.

brainjar status [--sync] [--workspace] [--project] [--short]

Flag	Description
`--sync`	Regenerate config file from active layers
`--workspace`	Show only workspace state
`--project`	Show only project overrides
`--short`	One-line output: `soul \| persona`

sync

Regenerate config file from active layers.

brainjar sync [--quiet]

Flag	Description
`--quiet`	Suppress output (useful in hooks)

compose

Assemble a full subagent prompt from a brain or ad-hoc layers.

brainjar compose <brain> [--task <text>]
brainjar compose --persona <name> [--task <text>]

Flag	Description
`--persona`	Ad-hoc persona name (fallback when no brain is saved)
`--task`	Task description to append to the prompt

The brain argument is the primary path — it resolves soul, persona, and rules from the brain file. Use --persona as a fallback when no brain is saved.

soul

Manage souls — the agent’s personality and values.

soul create

Create a new soul.

brainjar soul create <name> [--description <text>] [--content <text>]

Flag	Description
`--description`	One-line description of the soul
`--content`	Provide content directly instead of generating a template

soul list

List available souls.

brainjar soul list

soul show

Show a soul by name, or the active soul if no name given.

brainjar soul show [name] [--project] [--short] [--rev <n>]

Flag	Description
`--project`	Show project soul override (if any)
`--short`	Print only the active soul name
`--rev`	Show a specific version from history

soul history

List version history for a soul.

brainjar soul history <name>

soul revert

Restore a soul to a previous version (fetches old content and saves it as the current version).

brainjar soul revert <name> --to <version>

Flag	Description
`--to`	Version number to restore

soul update

Update a soul’s content.

brainjar soul update <name> --content <text>
cat content.md | brainjar soul update <name>

Flag	Description
`--content`	Provide content directly instead of reading from stdin

soul use

Activate a soul.

brainjar soul use <name> [--project]

Flag	Description
`--project`	Force project scope (auto-detected from `.brainjar/` dir)

soul drop

Deactivate the current soul.

brainjar soul drop [--project]

Flag	Description
`--project`	Force project scope (auto-detected from `.brainjar/` dir)

soul delete

Permanently delete a soul.

brainjar soul delete <name>

persona

Manage personas — role behavior and workflow for the agent.

persona create

Create a new persona.

brainjar persona create <name> [--description <text>] [--rules <list>] [--content <text>]

Flag	Description
`--description`	One-line description of the persona
`--rules`	Rules to bundle with this persona
`--content`	Provide content directly instead of generating a template

persona list

List available personas.

brainjar persona list

persona show

Show a persona by name, or the active persona if no name given.

brainjar persona show [name] [--project] [--short] [--rev <n>]

Flag	Description
`--project`	Show project persona override (if any)
`--short`	Print only the active persona name
`--rev`	Show a specific version from history

persona history

List version history for a persona.

brainjar persona history <name>

persona revert

Restore a persona to a previous version (fetches old content and bundled rules, saves them as the current version).

brainjar persona revert <name> --to <version>

Flag	Description
`--to`	Version number to restore

persona update

Update a persona’s content. Optionally update bundled rules.

brainjar persona update <name> [--content <text>] [--rules <list>]
cat content.md | brainjar persona update <name> [--rules <list>]

Flag	Description
`--content`	Provide content directly instead of reading from stdin
`--rules`	Update bundled rules

persona use

Activate a persona.

brainjar persona use <name> [--project]

Flag	Description
`--project`	Force project scope (auto-detected from `.brainjar/` dir)

persona drop

Deactivate the current persona.

brainjar persona drop [--project]

Flag	Description
`--project`	Force project scope (auto-detected from `.brainjar/` dir)

persona delete

Permanently delete a persona.

brainjar persona delete <name>

rules

Manage rules — behavioral constraints for the agent.

rules create

Create a new rule.

brainjar rules create <name> [--description <text>] [--content <text>]

Flag	Description
`--description`	One-line description of the rule
`--content`	Provide content directly instead of generating a template

rules list

List available and active rules.

brainjar rules list [--project]

Flag	Description
`--project`	Show project rules delta only

rules show

Show the content of a rule by name.

brainjar rules show <name> [--rev <n>]

Flag	Description
`--rev`	Show a specific version from history

rules history

List version history for a rule.

brainjar rules history <name>

rules revert

Restore a rule to a previous version (fetches old entries and saves them as the current version).

brainjar rules revert <name> --to <version>

Flag	Description
`--to`	Version number to restore

rules update

Update a rule’s content.

brainjar rules update <name> --content <text>
cat content.md | brainjar rules update <name>

Flag	Description
`--content`	Provide content directly instead of reading from stdin

rules add

Activate a rule or rule pack.

brainjar rules add <name> [--project]

Flag	Description
`--project`	Force project scope (auto-detected from `.brainjar/` dir)

rules drop

Deactivate a rule.

brainjar rules drop <name> [--project]

Flag	Description
`--project`	Force project scope (auto-detected from `.brainjar/` dir)

rules delete

Permanently delete a rule.

brainjar rules delete <name>

brain

Manage brains — full-stack configuration snapshots (soul + persona + rules).

brain save

Snapshot current effective state as a named brain.

brainjar brain save <name> [--overwrite]

Flag	Description
`--overwrite`	Overwrite existing brain

brain list

List available brains.

brainjar brain list

brain show

Show a brain configuration.

brainjar brain show <name>

brain use

Activate a brain — sets soul, persona, and rules in one shot.

brainjar brain use <name> [--project]

Flag	Description
`--project`	Force project scope (auto-detected from `.brainjar/` dir)

brain drop

Deactivate a brain — clears soul, persona, and rules.

brainjar brain drop <name>

brain delete

Permanently delete a brain.

brainjar brain delete <name>

pack

Export and import brainjar packs — self-contained shareable bundles.

pack export

Export a brain as a shareable pack directory.

brainjar pack export <brain> [--out <dir>] [--name <name>] [--version <ver>] [--author <name>]

Flag	Description
`--out`	Parent directory for the exported pack (default: cwd)
`--name`	Override pack name (and output directory name)
`--version`	Semver version string (default: `0.1.0`)
`--author`	Author field in manifest

pack import

Import a pack directory into the server.

brainjar pack import <path> [--activate]

Flag	Description
`--activate`	Activate the brain after successful import

hooks

Manage Claude Code hooks for brainjar.

hooks install

brainjar hooks install [--local]

Flag	Description
`--local`	Target project-local `.claude/settings.json`

hooks remove

Remove brainjar hooks from Claude Code settings.

brainjar hooks remove [--local]

Flag	Description
`--local`	Target project-local `.claude/settings.json`

hooks status

Show brainjar hook installation status.

brainjar hooks status [--local]

Flag	Description
`--local`	Target project-local `.claude/settings.json`

shell

Spawn a subshell with session-scoped state overrides.

brainjar shell [--brain <name>] [--soul <name>] [--persona <name>] [--rules-add <names>] [--rules-remove <names>]

Flag	Description
`--brain`	Brain name — sets soul, persona, and rules from brain file
`--soul`	Soul override for this session
`--persona`	Persona override for this session
`--rules-add`	Comma-separated rules to add
`--rules-remove`	Comma-separated rules to remove

reset

Remove brainjar-managed config from agent backend and restore backup.

brainjar reset [--backend claude|codex]

Flag	Description
`--backend`	Agent backend to reset (default: `claude`)

server

Manage the brainjar server.

server status

Show server status.

brainjar server status

server start

Start the local server daemon.

brainjar server start

server stop

Stop the local server daemon.

brainjar server stop

server logs

Show server logs.

brainjar server logs [--lines <n>] [--follow]

Flag	Description
`--lines`	Number of lines to show (default: 50)
`--follow`	Follow log output

server local

Switch to managed local server. Creates or switches to the local context.

brainjar server local

server remote

Switch to a remote server. Creates a context for the URL if one doesn’t exist.

brainjar server remote <url>

upgrade

Upgrade brainjar CLI and server to latest versions.

brainjar upgrade                    # upgrade both
brainjar upgrade --cli-only         # upgrade CLI only
brainjar upgrade --server-only      # upgrade server only

Flag	Description
`--cli-only`	Only upgrade the CLI
`--server-only`	Only upgrade the server binary

The server upgrade always targets the local binary, regardless of which context is active.

context

Manage server contexts — named server profiles for switching between local, staging, production, and team servers.

context list

List all contexts. The active context is marked.

brainjar context list

context add

Add a remote context. Validates the server is reachable before adding.

brainjar context add <name> <url> [--workspace <name>]

Flag	Description
`--workspace`	Workspace name (default: `default`)

context remove

Remove a context. Cannot remove local or the active context.

brainjar context remove <name>

context use

Switch active context. Syncs configuration from the new server.

brainjar context use <name>

context show

Show context details. Defaults to the active context.

brainjar context show [name]

context rename

Rename a context. Cannot rename local.

brainjar context rename <old> <new>

context set-token

Store an API key for a remote context.

brainjar context set-token <name> <key>

Cannot be used on local contexts — local contexts use auto-generated tokens.

api-key

Manage API keys for remote server authentication. All commands require local admin access (local token auth).

api-key create

Create a new API key. The plaintext key is returned once — save it immediately.

brainjar api-key create --name <name> [--user-id <id>] [--expires-in <duration>]

Flag	Description
`--name`	Key name (e.g. `ci-pipeline`)
`--user-id`	User ID label for the key
`--expires-in`	Expiration duration: `30d`, `90d`, `365d` (1-365 days)

api-key list

List all API keys (shows prefix only, not the full key).

brainjar api-key list

api-key revoke

Revoke an API key by ID.

brainjar api-key revoke <id>

migrate

Import file-based content into the server.

brainjar migrate [--dry-run] [--skip-backup]

Flag	Description
`--dry-run`	Preview what would be imported without making changes
`--skip-backup`	Skip renaming source directories to `.bak`

Integrations

completions

Generate shell completion script.

brainjar completions <bash|fish|nushell|zsh>

Setup examples:

eval "$(brainjar completions bash)"    # add to ~/.bashrc
eval "$(brainjar completions zsh)"     # add to ~/.zshrc
brainjar completions fish | source     # add to ~/.config/fish/config.fish

mcp add

brainjar mcp add [--agent <name>] [--command <cmd>] [--no-global]

Flag	Description
`--agent`	Target a specific agent (e.g. `claude-code`, `cursor`)
`--command`, `-c`	Override the command agents will run
`--no-global`	Install to project instead of globally

skills add

Sync brainjar skill files to your agent.

brainjar skills add [--depth <n>] [--no-global]

Flag	Description
`--depth`	Grouping depth for skill files (default: 1)
`--no-global`	Install to project instead of globally