Skip to content
Captain BarbossaDocsGitHubPyPI
DocsCLI reference

CLI reference

Every captain command, flag, and argument in one table.

Every captain command and flag, as the installed binary reports them. All NAME arguments are case-insensitive and accept the crew's display name, ID, or Herdr agent name.

Session and setup#

Session and setup commands
CommandPurpose
captain [--agent claude|codex|pi|grok] [--prompt TEXT] [--session ID] [--no-dashboard]Start a captain in this pane. See the captain.
captain --session ID ...Run any command against another shell's session.
captain sessionPrint the current session id.
captain updateUpgrade the installed tool.
captain init [--global]Write a commented .captain/settings.toml template. --global writes ~/.captain/settings.toml instead of the project's. See settings.
captain --versionPrint the installed version.

Deterministic work, no crew#

These spend no model and no pane. See when to recruit for the rule that picks them over a crew.

captain do
CommandPurpose
captain do commit --message MESSAGE [PATH ...]Stage the named paths and commit them. Omit the paths to commit what is already staged.
captain do pushPush the current branch, setting upstream on the first push.
captain do branch NAMECreate and switch to a new branch.
captain do switch NAMESwitch to a branch that already exists.
captain do fetchFetch from the remote, touching no file in the worktree.
captain do pullFast-forward the current branch. It never merges, rebases, or conflicts.
captain do run TARGETRun one target the project declares in its Makefile. One of build, check, clean, fmt, format, gate, help, install, lint, test, typecheck, vet.
captain inspect
CommandPurpose
captain inspect files [PATH]Enumerate files under a path.
captain inspect read PATHRead one regular UTF-8 text file.
captain inspect search TEXT [PATH]Search for literal, case-sensitive text.
captain inspect state session|project|repo [PATH]Read a literal path within one stored scope. Crew are limited to repo.
captain inspect git status|log|current-branch|root|diff|branches|ls-files|grep [--staged] [--text TEXT]Fixed Git queries in an ordinary local checkout. grep takes its pattern from --text, literal and case-sensitive.

One model turn, no pane#

captain quiet
CommandPurpose
captain quiet --task TEXT [--diff worktree|staged] [--write PATH] [--model MODEL] [--timeout SECONDS]Spend one headless model turn: no pane, no assignment, no wait. --write is repeatable and the turn is read-only without it. --timeout defaults to 900 seconds. See quiet turns.

Crew#

Crew commands
CommandPurpose
captain crew [NAME] --task TEXT [--owns PATH] [--allow ACTION] [--handoff ASSIGNMENT_ID] [--agent claude|codex|pi|grok] [--placement pane|tab] [--direction vertical|horizontal|auto] [--split-pane ID|auto] [--model MODEL]Recruit crew. --owns and --allow are repeatable. See crew.
captain status [--all]Print a table of this session's crew. --all includes dismissed crew.
captain focus NAMEFocus a crew's pane and tab.
captain interrupt NAME [--reason REASON]Stop a crew's current turn, keeping its pane and assignment. --reason is recorded in session memory.
captain model NAME cheap|mid|strong|MODELSwitch a running crew's model. Accepts a tier, model name, or alias. See models.
captain dismiss NAMEClose and retire crew.

Assignments and mail#

Protocol commands
CommandPurpose
captain wait NAME [--json] [--ack DELIVERY_ID] [--timeout SECONDS]Read and acknowledge a crew notification. --timeout falls back to [crew] wait_timeout, 86400 seconds (a full day) by default.
captain tell NAME MESSAGE [--assignment ID]Append a follow-up to an active assignment. --assignment is required for protocol crew.
captain inbox NAMEPrint a crew's queued mail oldest first and write the read receipt.
captain assign NAME --task TEXT --handoff ASSIGNMENT_ID [--owns PATH] [--allow ACTION]Start the next assignment after acknowledged completion. Both --task and --handoff are required.
captain ask NAME QUESTION [--assignment ID] [--incarnation ID]Record one pending question. Both IDs may default for newly launched crew.
captain answer NAME QUESTION_ID MESSAGE --assignment ID [--incarnation ID]Answer that question. --assignment is required.
captain done NAME --report TEXT [--assignment ID] [--incarnation ID]Record explicit completion. --report is required.
captain check NAME ACTION [PATH ...] [--assignment ID] [--incarnation ID]Check grants. Executes nothing.

ACTION is one of read, search, edit, test, build, format, commit, version, delete. Full semantics — acknowledgement, mail receipts, and the gates on the doorbell — are in assignments and mail, and the grants themselves in ownership.

Dashboard#

Dashboard command
CommandPurpose
captain dashboard [--interval SECONDS] [--once] [--refresh-prices]Refresh a crew token-usage table in this pane until interrupted. --interval falls back to [dashboard] interval, and --once prints a single frame and exits. See dashboard.

Memory#

Memory commands
CommandPurpose
captain memory add SUBJECT RELATION TARGET [--scope session|project|repo] [--because RATIONALE] [--supersede]Save a relationship. --because is required with --scope repo, whose relation must be convention|decided|method.
captain memory init [--from PATH] [--apply]Seed repo memory from the project rulebook. A preview without --apply; --from defaults to AGENTS.md then CLAUDE.md.
captain memory query QUESTIONSearch session, project, and repo memory with Graphify.
captain memory show [--scope session|project|repo] [--json] [--all]Print relationships. --all shows every link instead of the most recent 25.
captain memory path [--scope session|project|repo]Print a scope's directory without creating it.
captain memory prune [--older-than DAYS]Remove finished sessions' memory directories. Default 7 days.

Scope behaviour, the closed relation vocabulary, and pruning safeguards are in memory.

A worked session#

shell
captain --agent codex
captain crew Gibbs --task "Rewrite the docs content" \
  --owns src/content --allow edit --allow build
captain wait Gibbs
captain wait Gibbs --ack <delivery-id>
captain tell Gibbs "also add a search box" --assignment <assignment-id>
captain done Gibbs --report "..."        # run by Gibbs, not the captain
captain dismiss Gibbs
captain do commit --message "Add the docs site" src/content src/app/docs