Command reference — docs

The complete command surface of crab 0.4.0: two report subcommands and five flags. This page is short on purpose.

Usage

crab [OPTIONS] [COMMAND]

Commands:
  trace    Render the span tree of a session file (turn -> llm/tool calls)
  metrics  Token/cost/latency report from the local metrics database
  help     Print this message or the help of the given subcommand(s)

Options:
  -p, --print <PRINT>        Run once non-interactively and print the final response
  -c, --continue             Continue the most recent session in .crab/sessions
      --yolo                 Allow all tool calls without confirmation
      --provider <PROVIDER>  Provider profile name from ~/.crab/config.toml
                             (or "mock" for debugging). Omit to use the
                             config's default_provider
      --system <SYSTEM>      Extra system prompt appended after base + AGENTS.md
  -h, --help                 Print help
  -V, --version              Print version

Flags

Flag	Effect	Notes
`-p, --print <TEXT>`	Run one prompt, print the final response, exit.	Non-interactive: tool calls are auto-approved.
`-c, --continue`	Resume the latest session in this project.	Replays the log to seed exact token and context counters.
`--yolo`	Approve every tool call for this run.	Per run, not persistent. See Run crab safely.
`--provider <NAME>`	Use a named profile for this run.	`mock` is a built-in stub — canned replies, no network, no cost.
`--system <TEXT>`	Append to the system prompt.	After the base prompt and `AGENTS.md`, before history.

Subcommands

crab trace

crab trace <FILE> [--json]

Arguments:
  <FILE>

Options:
      --json  Structured JSON instead of the text tree

Reads a session file and prints its span tree. Never writes. See Trace & metrics for how to read the columns.

crab metrics

crab metrics [DAYS] [--json]

Arguments:
  [DAYS]  Window in days (default 7) [default: 7]

Options:
      --json  Structured JSON instead of the text report

Queries .crab/metrics.sqlite in the current working directory. If the file does not exist yet there is nothing to report — the ledger is created by the first run, not at install time.

Environment

Variable	Effect
`CRAB_API_KEY`	API key. `OPENAI_API_KEY` is used if this is unset.
`CRAB_BASE_URL`	Overrides `base_url`. `OPENAI_BASE_URL` also works.
`CRAB_MODEL`	Overrides `model`.
`CRAB_CONTEXT_WINDOW`	Overrides `context_window`.

Environment beats the profile field by field, so one config can serve a laptop and a CI runner with different keys.

Slash commands

Type / to browse with descriptions — ↑↓ to choose, Enter to complete, Esc to dismiss. After /model and /skill: the hint also completes arguments.

Command	Effect
`/quit` (/exit, /q)	Leave crab.
`/yolo`	Toggle allow-all: auto-approve every tool call for the rest of the session.
`/model <name>`	Switch to the named provider profile.
`/models`	Picker over your profiles; fills `/model`.
`/skill:<name> [args]`	Inject a discovered skill's instructions as a user message.
`/skills`	Picker listing discovered skills; fills `/skill:<name>` into the input.
`/compact`	Compact the conversation now: shed old tool results, summarise if needed.

Keys

Ctrl+C while running: Abort the current run — not exit. Text and completed tool results stay on disk, so --continue works.
Ctrl+C at an idle prompt: Clear the input line.
Drag to select: Release copies pi-style: pbcopy on macOS, OSC 52 elsewhere.

Scripting

-p is the integration point. It prints the final response to stdout and exits, so it composes with anything:

# summarise a diff in CI
git diff origin/main | crab -p "summarise this diff for a changelog"

# fail a build if the agent cannot find what it needs
crab -p "does src/parser.rs handle CRLF?" > answer.txt || exit 1

# exercise the loop without spending money or touching the network
crab -p "hello" --provider mock

There is no JSON event mode yet. -p prints text. The structured outputs today are crab trace --json and crab metrics --json. If you need per-event streaming, read the session file after the run — it has every span.

← PreviousRun crab safely Next →Tool contracts