CLI reference¶

The authoritative reference for every claude-coder command, its flags, and its exit codes.

The binary is claude-coder. Invoke it as claude-coder <command> [args].

Global flags¶

--config and --verbose are parsed after the command, e.g. claude-coder doctor --config ./x.json. The command must be the first argument — claude-coder --config ./x.json doctor is rejected with unknown command '--config' (exit 2). The help and version flags differ: --help/-h works both as a leading flag (global help) and after a command (<command> --help prints that command's usage); --version/-v works only as the leading argument (claude-coder --version).

Flag	Behavior
`--config <path>`	Profiles config file (absolute or cwd-relative). See discovery order below.
`--verbose`	Print full stack traces on error.
`--help`, `-h`	Show global help, or `<command> --help` for one command's usage.
`--version`, `-v`	Print the version (currently `0.0.0`).

Config discovery order¶

The config file is resolved in this order:

Explicit --config <path>.
Project-local ./claude-coder.config.json, if it exists.
Default ~/.claude/claude-coder/profiles.json.

If --config is given but the file is missing, the CLI fails loud (exit 1). If only the default path is used and no file exists, the CLI runs with built-ins only — no error. A malformed file, or a profile that sets a billed credential, is rejected at load time. See profiles and security.

Subscription auth only

Auth is always your Claude subscription via claude /login OAuth. A profile that sets ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, or AWS_BEARER_TOKEN_BEDROCK (among other billed-credential and auth-redirect vars) is rejected. See security for the full deny set. Never put an API key in a profile or your environment.

Exit codes¶

Code	Meaning
`0`	Success.
`1`	Runtime error (auth, config, transport, profile).
`2`	Usage error (unknown command, missing/extra arg, unknown flag).
`130`	Interrupted by SIGINT/SIGTERM (Ctrl-C).

A usage error prints the offending command's usage line to stderr:

$ claude-coder resume
resume: missing required argument(s)
Usage: claude-coder resume <name> ["<prompt>"] [--graceful]
# exit 2

Quote your prompts

A multi-word prompt must be a single quoted argument. An unquoted prompt becomes extra positionals and is rejected with exit 2 rather than silently truncated.

repl¶

Interactive multi-turn loop over a single session created from a profile. Ctrl-C interrupts; exit closes.

Usage: claude-coder repl <profile> [--cwd <dir>] [--graceful]

Arg	Required	Meaning
`<profile>`	yes	Profile name (from config or the built-in).

Flag	Default	Meaning
`--cwd <dir>`	—	Working directory. Precedence: `--cwd` > profile `cwd` > invocation cwd.
`--graceful`	false	On exit, close in an orderly way — cleanly interrupt an in-flight turn (it settles as `interrupted`) instead of an abrupt close. It does not wait for the turn to finish.

Behavior. Creates a session from the profile, reads lines from stdin, runs each as a prompt, and prints results. Empty lines are ignored; exit ends the loop. Ctrl-C is two-stage: the first SIGINT during an active turn interrupts that turn without closing the session; a second SIGINT (or one with no active turn) closes and exits. EOF or exit closes with exit 0. To reattach a persisted session for a sustained conversation, use resume.

# requires subscription auth + a valid `claude` binary
claude-coder repl claude-code-expert

list¶

List persisted plus live-this-process sessions.

Usage: claude-coder list [--json]

Flag	Default	Meaning
`--json`	false	Output the merged array as JSON.

Behavior. Merges reconciled persisted sessions with live in-process ones; a live row wins over a persisted row of the same name.

$ claude-coder list
(no sessions)

resume¶

Reattach a persisted session, and run a turn if a prompt is given.

Usage: claude-coder resume <name> ["<prompt>"] [--graceful]

Arg	Required	Meaning
`<name>`	yes	Session name.
`<prompt>`	no	If given, run one turn; otherwise just show the session state.

Flag	Default	Meaning
`--json`	false	Print the turn result (or session view) as JSON.
`--graceful`	false	Close in an orderly way — cleanly interrupt an in-flight turn (it settles as `interrupted`) rather than abruptly (applies when a prompt is run).

Behavior. Reattaches the session. With a prompt, runs one turn and prints the result. Without a prompt, prints the session view (name, profile, transport, state, id, cwd). Closes on exit.

claude-coder resume my-session                # show state
claude-coder resume my-session "keep going"   # run one turn

fork¶

Branch a persisted session under a new name.

Usage: claude-coder fork <name> [--name <new>] [--graceful]

Arg	Required	Meaning
`<name>`	yes	Existing session to fork from.

Flag	Default	Meaning
`--name <new>`	—	New session name. Omit for an auto-generated name.
`--json`	false	Print the forked session view as JSON.
`--graceful`	false	Accepted for consistency; no turn runs on `fork`.

Behavior. Creates a branched session and prints its view.

claude-coder fork my-session --name my-copy

history¶

Read a session's transcript history.

Usage: claude-coder history <name> [--json]

Arg	Required	Meaning
`<name>`	yes	Session name.

Flag	Default	Meaning
`--json`	false	Output the history entries as a JSON array.

Behavior. Prints each transcript entry. Human output is tab-separated type<TAB>uuid per line.

claude-coder history my-session

tui¶

Open the interactive multi-session TUI over the fleet. This is the quick reference; see tui for the full guide.

Usage: claude-coder tui [--cwd <dir>] [--graceful]

Flag	Default	Meaning
`--cwd <dir>`	—	Working directory for sessions created in the TUI.
`--graceful`	false	Close in an orderly way — cleanly interrupt in-flight turns (they settle as `interrupted`) instead of an abrupt close.

Behavior. A long-running terminal UI. It blocks until you quit (Ctrl-C or the quit key) and restores the terminal on exit. Exits 0 on clean quit, 1 on error.

claude-coder tui

doctor¶

Verify your setup with read-only checks: subscription auth, config, and git-hooks.

Usage: claude-coder doctor [--json]

Flag	Default	Meaning
`--json`	false	Output the report (checks + overall status) as JSON.

Behavior. Runs independent, read-only checks (never spawns a process). A broken config is reported as a row, never thrown. Exits 0 if all checks pass or warn, 1 if any check fails.

$ claude-coder doctor
✓ auth            subscription OAuth (no billed credential in force)
✓ config          no profiles file (built-ins only)
✓ git-hooks       no .githooks/pre-commit in this repo (nothing to activate)

✓ overall: pass

The git-hooks check is advisory (never a fail): if the current repo ships a .githooks/pre-commit secret-leak guard, it reports whether that guard is active (core.hooksPath=.githooks) so a fresh clone that skipped npm install doesn't silently lose its local secret gate. A repo without one is pass ("nothing to activate").

serve-api¶

Run a loopback HTTP server that speaks the Anthropic Messages API wire format, backed by your subscription — point an Anthropic-SDK app at it for local dev with zero code changes. This is the quick reference; see Local API gateway for the full guide.

Usage: claude-coder serve-api [--port N] [--config <path>]

Flag	Default	Meaning
`--port <N>`	0	Port to bind on `127.0.0.1`. `0` = OS-assigned.
`--config <path>`	—	Profiles config file (global flag).

Behavior. Binds 127.0.0.1:<port> (loopback only — there is no --host), prints the URL once, then blocks until Ctrl-C. Each POST /v1/messages creates a fresh ephemeral session, runs one turn on the subscription, and tears it down. Like the other session commands it fails closed at startup if any credential env var (e.g. ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL) is in force. Exits 0 on clean close, 1 on error, 130 on SIGINT/SIGTERM.

$ claude-coder serve-api --port 8787
claude-coder api listening on http://127.0.0.1:8787

Local dev shim

Auth is always your subscription login; the incoming x-api-key header is ignored (and redacted). It is a best-effort dev shim, not a faithful raw-model proxy — see Local API gateway for the endpoint list, streaming, error mapping, and non-goals.