CLI Reference

Global flags link

All commands accept:

Agent mode is auto-detected when running inside a graith session or other AI agent environment (Claude Code, Cursor, Copilot, Amazon Q, OpenCode). Override with GR_AGENT_MODE=0 to disable or GR_AGENT_MODE=1 to force.

Session management link

gr new <name> (alias: n) link

Create a new agent session.

The --headless flag runs the agent in Claude Code’s stream-json mode rather than an interactive terminal — suited to fire-and-forget sessions no human will attach to (tribunal judges, trigger briefings). graith parses the typed event stream, so gr logs -f shows rendered output and the run’s cost/token usage is captured from the result envelope. It is experimental and inert unless [headless] experimental = true is set in config; it is Claude-only in v1, requires a prompt (-p), runs one-shot (one prompt, run to completion, exit), and is incompatible with the sandbox in v1 (a --headless request with the sandbox enabled is an error). Asking for --headless on an agent that can’t do it is an error, not a silent downgrade to PTY. Because a headless session can’t be attached, --headless implies --background. See Configuration → Headless sessions and Session Lifecycle → Headless sessions.

When a session is created:

1. Fetches origin (if fetch_on_create is true)
2. Creates branch <branch_prefix>/<session-name>-<session-id> from the base branch
3. Creates a worktree at <data_dir>/worktrees/<repo-name>/<repo-hash>/<session-id>/
4. Starts the agent process in the worktree
5. Attaches (unless --background)

gr attach [name-or-id] (alias: a) link

Attach to a session. If no name is given, opens the session picker overlay.

A headless session has no PTY to stream, so gr attach on one is not supported yet — graith directs you to gr logs -f <name>, which streams its rendered output read-only. Convert-to-interactive on attach (relaunching the agent in a PTY via claude --resume <session-id>, preserving history) is a planned follow-up (issue #1075).

gr stop <name-or-id> link

Stop a running session. The agent process is killed but the worktree and branch are preserved for later resumption.

When --children is used without a positional argument inside a graith session, it auto-resolves the current session from GRAITH_SESSION_ID and excludes it from the stop.

gr restart <name-or-id> link

Restart a stopped session. The agent process is restarted in the existing worktree using the agent’s resume_args.

gr delete <name-or-id> (alias: rm) link

Delete a session. Kills the agent process, removes the worktree, and deletes the branch. Prompts for confirmation if there are uncommitted changes or unpushed commits.

gr fork <source-session> <new-name> link

Fork a session. Creates a new worktree (from the source session’s branch), a new branch, and a new agent process. If the agent has fork_args configured, the new agent inherits the source agent’s conversation history.

gr migrate <name-or-id> link

Migrate a session to a different agent in place — for example, switch from Claude to Codex during a provider outage without losing your work. The current agent’s conversation is rendered to a neutral context file, the agent is stopped, and the target agent is started in the same worktree seeded with that history. The session keeps its id, name, worktree, and branch, so all code state (commits and uncommitted edits) carries over with no branching.

This is a lossy reseed, not a native resume: reasoning/thinking and exact tool-call replay are not carried over, and the agent process is restarted (attached clients re-attach to the new agent). If the target agent fails to start, the original agent is restored. Claude and Codex are supported as migration sources; any configured agent can be a target.

gr rename <name-or-id> <new-name> link

Rename a session.

gr star <name-or-id> link

Star a session. Starred sessions are protected from accidental deletion and appear in the Starred view.

gr unstar <name-or-id> link

Remove the star from a session.

Information and monitoring link

gr list (alias: ls) link

List all sessions with status.

The --wide view adds a Tokens column with the compact total token usage for each session’s current agent (a trailing ~ marks an approximate count). See gr tokens for the full breakdown.

gr tokens [session] link

Show per-session token usage — input, output, and cache tokens — extracted from each agent’s on-disk transcript. With no argument it lists every session and a grand total; with a session name or ID it shows just that session.

Counts reflect the session’s current agent and are updated by a background poll, so they lag by up to ~30 seconds. Agents without a transcript reader (currently anything other than Claude Code and Codex) show — / (unsupported); a session that hasn’t been observed yet shows (unknown), distinct from a real zero. USD cost is not shown (a planned opt-in via a user-supplied price table).

  $ gr tokens
SESSION   AGENT   INPUT    OUTPUT   CACHE-R    CACHE-W   OTHER   TOTAL
braw      claude  12,431   48,209   1,204,882  96,004    0       1,361,526
canny     codex   69,131   3,517    756,224    0         0       828,872
  

Use --json (implied in agent mode) for a structured per-session projection.

gr logs <name-or-id> (alias: l) link

Show session output without attaching.

gr info link

Show info for the current session. Auto-detects the session by matching the current working directory against session worktree paths.

gr dashboard link

Live-updating TUI dashboard of all sessions. Supports inline attach, stop, delete, and resume.

gr approvals link

List sessions waiting for approval.

gr doctor (alias: doc) link

Run health checks and diagnostics. Checks daemon status, safehouse availability, orphaned worktrees, oversized scrollback files, and stale PID files.

By default gr doctor avoids walking the data dir to measure on-disk sizes — that walk can take tens of seconds on a large install (worktrees full of node_modules and .git objects), so it’s opt-in. Pass --disk to report the size of the data dir, tmp repos, and orphaned worktrees. When it finds leftover artifacts whose size is worth knowing (orphaned worktrees, a legacy directory), the default run recommends re-running with --disk. In --json output, the disk_measured field indicates whether sizes were computed.

gr sandbox why link

Explain whether the configured sandbox would allow or deny a filesystem or network access, without launching an agent. Builds the nono profile graith would generate from config and queries nono’s policy oracle. Requires the nono backend.

  gr sandbox why --path ~/.ssh/id_rsa --op read
gr sandbox why --host github.com --port 443
  

Remote interaction link

gr type <name-or-id> <text> (alias: t) link

Type text into a session’s PTY stdin. Appends a newline by default.

gr status [session] <message> link

Set a status summary for a session, visible in the session picker overlay and gr list. When run inside a graith session, the session is auto-detected.

gr notify <message> link

Send a proactive desktop/push notification via the configured [notifications] backend. Unlike an inbox message, a notification proactively gets the human’s attention. Only the orchestrator session and the human may send notifications (plain agent sessions are rejected).

  gr notify "Morning briefing ready" --priority low
gr notify "CI failing on main after 3 retries" --priority high
  

See Configuration → Notifications for backends, rate limiting, and quiet hours.

Messaging link

See Inter-Agent Messaging for full details.

gr msg pub <body> link

Publish a message to a stream.

gr msg send <session> [body] link

Send a message to a session’s inbox. By default, also types a notification into the session’s PTY.

gr msg sub link

Read messages from a stream.

gr msg ack link

Acknowledge all messages in a stream.

gr msg topics link

List streams with total and unread message counts.

gr msg jail list link

List PR comments quarantined by the author-trust gate (see Comment author-trust gate).

gr msg jail show <id> link

Show a single quarantined comment, including its body.

gr msg jail release [id] link

Release a quarantined comment — deliver its content to the target session’s inbox. Restricted to the human or the orchestrator; a plain agent session is rejected.

Document store link

See Document Store for full details.

gr store put <key> [body] link

Store a document. Reads from stdin if no body or --file is given.

gr store get <key> link

Retrieve a document. Outputs the raw body.

gr store list [prefix] (alias: ls) link

List documents, optionally filtered by key prefix.

gr store append <key> [line] link

Append a line to a document. Creates the document if it does not exist. Reads from stdin if no body or --file is given.

gr store rm <key> link

Remove a document from the store.

Store persistent flags link

All store subcommands accept:

Scenarios link

See Scenarios for full details.

gr scenario start <file> link

Start a scenario from a TOML file. Pass - to read from stdin. Only the orchestrator session can start scenarios.

  gr scenario start tracing.toml
cat tracing.toml | gr scenario start -
  

gr scenario status <name> link

Show the status of each session in a scenario.

gr scenario list link

List all scenarios with their aggregate status.

gr scenario stop <name> link

Stop all running sessions in a scenario.

gr scenario delete <name> link

Delete a scenario and all its sessions, including worktrees and branches.

Triggers link

Daemon-fired automation on a schedule or on file changes. Triggers are defined in config.toml; these commands inspect and control them. See Triggers for the full model.

gr trigger list link

List all configured triggers with their source, action, next fire / watch scope, and state.

gr trigger status <name> link

Show detail for one trigger: next fire, last run/result/error, and (for watch triggers) live bindings.

gr trigger run <name> link

Fire a schedule trigger once, now (respects the overlap policy).

gr trigger pause <name> / gr trigger resume <name> link

Pause a trigger (persists across restart) or resume a paused one. Requires the orchestrator or a descendant.

Daemon management link

gr daemon start link

Start the daemon. This is normally automatic and rarely needed.

gr daemon stop link

Stop the daemon gracefully.

gr daemon restart link

Restart the daemon, preserving live sessions via exec.

After rebuilding gr, run gr daemon restart to pick up the new daemon binary.

gr daemon reload link

Reload configuration without restarting the daemon.

Other commands link

gr config show link

Print the effective (merged) configuration.

gr config diff link

Show changes from built-in defaults.

gr config reset link

Write built-in defaults to the config file.

gr mcp link

Run graith as an MCP (Model Context Protocol) server over stdio. See MCP Server.

Subcommands inspect and control the daemon-managed MCP servers declared under [[mcp_servers]]:

gr mcp list and gr mcp logs are read-only; gr mcp restart requires the caller to be the human, the orchestrator, or one of its descendants.

gr completion <shell> link

Generate a shell completion script. Supported shells: bash, zsh, fish, powershell.

gr version link

Print version information.

Hidden/internal commands link

These are used by graith internally and are not intended for direct use: