> ## Documentation Index > Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI commands > Command reference for the task-first, Unix-native rkat CLI. `rkat` is designed for three main workflows: * interactive terminal use * scripts and CI * Unix pipes and chained command composition The default path is prompt-first: ```bash theme={null} rkat "summarize this repository" ``` You can also use subcommands explicitly: ```bash theme={null} rkat run "summarize this repository" rkat run --resume last "keep going" rkat mob pack ./mobs/release-triage -o dist/release-triage.mobpack ``` ## Global flags The top-level parser exposes the same realm and convention-root flags to each command family: ```bash theme={null} rkat [--realm ] [--isolated] [--instance ] \ [--realm-backend ] \ [--state-root ] \ [--context-root ] \ [--user-config-root ] \ [--default-model ] \ ``` `--default-model ` persists the default agent model into the scope-resolved config (project/user/realm resolution included) and exits when given without a command — `rkat --default-model claude-fable-5` is the one-liner for switching what every future run talks to. The model is validated against the catalog and configured custom models. By default, CLI commands use the current directory as the invocation context and derive a stable workspace realm id from that path. For project-local state, `StorageLayout` walks upward to the nearest ancestor containing a `.rkat` entry and stores realms under `/.rkat/realms//`. When no ancestor contains `.rkat`, the context root is the project root fallback. `--context-root` changes the derived workspace identity and the starting point for that ancestor search; it does not necessarily change the project root when both contexts are inside the same project. `--state-root` bypasses discovery and changes only where realm directories are stored. Some maintenance or host commands reject combinations that have no safe meaning. In particular, storage verbs reject `--isolated` and `--default-model`, and `rkat mob host` rejects `--isolated`. Fresh prompt-first runs and `rkat help` are fail-soft only at the default workspace storage boundary. If the workspace-derived realm cannot be opened, no historical session from that realm is loaded into the fresh run, and the explicit compatibility bridge is never invoked automatically. The ordinary strict open may already have completed supported manifest initialization or an earlier domain migration before a later store refuses. The CLI warns and creates a new generated realm using durable SQLite under the same resolved state root. The workspace's configuration, auth policy, provider selection, and tool policy remain in force; only persistence-owned state is isolated in the generated realm. The warning names both realms and prints the explicit recovery command: ```bash theme={null} rkat --state-root --realm storage migrate --apply --bridge-pre-0-8-10 ``` An explicit `--realm`, `--isolated`, every resume form, and all `session` commands remain fail-closed. Historical session access therefore stays an explicit maintenance operation. The fresh-run fallback is never an in-memory session and never makes a historical session from the failed workspace realm part of the new run. ## Common commands | Command | Purpose | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `rkat ` | Run a task directly from the terminal | | `rkat run ` | Explicit form of the default prompt command | | `rkat run --resume[=] ` | Continue a saved session | | `rkat help ` | Ask how to use Meerkat (embedded platform skill) | | `rkat session ...` | Inspect, delete, or interrupt sessions | | `rkat realm ...` | Inspect or manage realms | | `rkat config ...` | Read or update CLI/runtime config | | `rkat auth ...` | Log in, inspect auth profiles, test bindings, and refresh/logout credentials | | `rkat blob ...` | Inspect and retrieve stored blob content | | `rkat mcp ...` | Manage local/project MCP server config | | `rkat mob ...` | Pack, inspect, validate, deploy, and build mob artifacts | | `rkat workgraph ...` | Inspect WorkGraph items, ready work, snapshots, and events | | `rkat skill ...` | Manage configured skill sources and inspect available skills | | `rkat models` | List built-in models plus configured self-hosted aliases | | `rkat capabilities` | Show runtime capabilities | | `rkat doctor` | Check local setup, provider keys, and self-hosted server reachability | | `rkat storage doctor` | Read-only storage diagnosis (realm inventory, schema ledgers, split-brain twins, structural integrity) | | `rkat storage migrate` | Offline, fenced storage migration (dry-run by default) | | `rkat storage prune` | Lifecycle for registered storage backup artifacts | | `rkat init` | Create project config from the global template | ## Prompt-first usage ```bash theme={null} rkat [OPTIONS] rkat run [OPTIONS] ``` Examples: ```bash theme={null} rkat "summarize this repository" cat story.txt | rkat "summarize the story" git diff | rkat run --json "review these changes" tail -f app.log | rkat run --stdin lines "watch for incidents" rkat run -t workspace "fix the failing test" rkat run --yolo --param temperature=0.2 "take the gloves off" ``` ### Common run flags * `-m, --model ` * `-o, --output ` * `--json` * `-s, --stream` * `--no-stream` * `--no-web-search` * `--export-atif` (write an ATIF trajectory to the realm `trajectories/` directory after the turn; default off) * `--resume[=]` * `--skill ` repeatable * `-d, --max-duration ` * `-t, --tools ` * `--stdin ` * `--keep-alive` * `--wait-for-mcp` * `--mcp-auth ` * `-v, --verbose` For the full advanced set, use: ```bash theme={null} rkat run --help ``` Current CLI help labels this value `PATH_OR_ID`, but `rkat run --skill` and resume currently construct builtin skill keys. Direct local-path preload is therefore unsupported. `rkat skill add ` registers a filesystem source but does not make this flag source-aware, and ordinary CLI sessions do not currently advertise the skill-discovery tool set. Use typed RPC/SDK preload fields when a host must address a source UUID directly. ### Tool presets `rkat` uses presets instead of many enable/disable booleans. | Preset | Meaning | | ----------- | --------------------------------------------------------------------- | | `safe` | Builtins, skills, configured MCP, delegated-work-safe tools; no shell | | `workspace` | `safe` plus shell access | | `full` | All CLI-side capabilities, including memory and mob tools | | `none` | No tools | `--yolo` is an alias for `--tools full`. ### Provider and structured output controls Use `--param` for common tuning and `--params-json` as the escape hatch: ```bash theme={null} rkat -m claude-sonnet-4-6 \ --param temperature=0.2 \ --param max_output_tokens=4000 \ "triage this incident" ``` Structured output is file-friendly: ```bash theme={null} rkat --schema ./triage.schema.json "extract issues from this diff" ``` `--json` is a convenience alias for `--output json`. HTML output asks the agent to make the final answer a standalone local HTML artifact: ```bash theme={null} rkat run --html "explain how prompt caching works in this repo" rkat run --browser "create a visual implementation plan for this change" ``` `--html` is a convenience alias for `--output html`. `--browser` is a compact shortcut for HTML output plus `--open-in-browser`. HTML output writes the file under the active realm's `presentation/html` directory and prints the path. Template defaults live under `[presentation.html]`: ```toml theme={null} [presentation.html] default_template = "polished" [presentation.html.templates.review] path = "html/review.md" [presentation.html.templates.dense] body = "Render this as a dense technical artifact with annotated snippets." ``` Per run, use `--html-template ` or `--html-template-file `. Config template paths are resolved relative to the active config base directory. ### Streaming defaults * In a TTY, text output streams by default. * In pipes and scripts, streaming is off by default. * JSON and HTML output stay non-streaming by default so stdout remains machine-friendly unless `--stream` is explicitly requested. ### Stdin modes and Unix pipes `rkat` treats piped stdin as a first-class interface: * `auto` default: if stdin is piped, read it as one blob of context * `blob`: always read full stdin to EOF before running * `lines`: keep stdin open and process one line at a time * `off`: ignore stdin even if something is piped in Batch blob mode: ```bash theme={null} cat story.txt | rkat "summarize the story" git diff | rkat "review these changes" cat notes.txt | rkat "extract action items" | rkat "group these by owner" ``` Live line mode: ```bash theme={null} tail -f app.log | rkat run --stdin lines "watch for incidents and call them out" ``` `--line-format json` treats each incoming line as JSON instead of plain text. ## run --resume ```bash theme={null} rkat run --resume[=] [OPTIONS] ``` Examples: ```bash theme={null} rkat run --resume last "keep going" rkat run --resume ~2 "pick this thread back up" cat notes.txt | rkat run --resume "merge these notes into the plan" tail -f app.log | rkat run --resume --stdin lines "watch for new incidents" ``` `SESSION_ID` accepts: * a full UUID * a short prefix * `last` * `~N` Omitting the value means `last`, so `rkat run --resume "keep going"` and `rkat run --resume last "keep going"` are equivalent. Resume supports the same stdin model as `run`, plus per-turn tool overlays and provider params. Self-hosted aliases work the same way: ```bash theme={null} rkat run --resume -m gemma-4-31b "Continue with the local model" ``` ## session ```bash theme={null} rkat session list [--limit ] [--offset ] [--label ] rkat session show rkat session export-atif [--output ] rkat session delete rkat session interrupt ``` This is the human/operator session surface. CLI-internal control-plane session APIs are not exposed here. `session export-atif` reads the currently available event audit/replay projection. A slow live subscriber can receive a typed stream-truncation marker without dropping projector input, but projection is asynchronous best-effort derived state and export does not first drain it to the latest committed session boundary. Meerkat supports ordinary durable-state opens from 0.8.10 onward. For an older SQLite realm, stop every process that can access it and run the explicit current maintenance bridge: ```bash theme={null} rkat --state-root --realm storage migrate --apply --bridge-pre-0-8-10 ``` The frozen importer fails closed on unsupported pre-floor shapes. Normal realm opens remain strict. JSONL and memory realms are rejected before any database is mutated. The maintenance transaction preserves queued and nonterminal input rows without scheduling or replaying them. A later session activation follows normal recovery. ## blob ```bash theme={null} rkat blob get [--output ] [--json] ``` Without either output flag, `blob get` writes the decoded raw bytes to stdout. `--output` writes those bytes to a file. `--json` prints the complete `BlobPayload` (`blob_id`, `media_type`, and base64 `data`) instead of raw bytes. Blob IDs are realm-scoped, so use the same realm that produced the session or artifact reference. ## realm ```bash theme={null} rkat realm current rkat realm list rkat realm show rkat realm create [--backend ] rkat realm delete [--force] rkat realm prune [--isolated-only] [--older-than-hours ] [--force] ``` `realm current` prints the realm selected by the CLI scope. `realm list` and `realm show` inspect manifests in the active state root. `realm prune` defaults to a 24-hour age threshold. `--force` bypasses active-lease safety checks, so use it only after confirming that no process still owns the target realm. ## config ```bash theme={null} rkat config get [--format toml|json] [--with-generation] rkat config set [] [--json | --toml ] [--expected-generation ] rkat config patch [] [--json ] [--expected-generation ] ``` The positional argument is always a file path; inline payloads use `--json` (or `--toml` for `set`). Examples: ```bash theme={null} rkat config get --format toml rkat config set ./.rkat/config.toml rkat config patch --json '{"agent":{"model":"gpt-5.5"}}' rkat config patch --json '{"self_hosted":{"servers":{"ollama":{"transport":"openai_compatible","base_url":"http://127.0.0.1:11434","api_style":"chat_completions"}}}}' ``` ## auth ```bash theme={null} rkat auth realms # list realms defined in config rkat auth profiles # list profiles/backends/bindings rkat auth profile # inspect one profile rkat auth login [] [--backend ] [--method ] [--non-interactive --secret ] rkat auth status # realm config shape + AuthMachine lease lifecycle state rkat auth test # dry-run resolve the binding rkat auth refresh # force-refresh OAuth tokens rkat auth logout [:] # clear persisted credentials; bare means global rkat auth profile-delete -y ``` `rkat auth login` provisions the reserved **`global`** realm in the home-rooted doc at `~/.rkat/config.toml` — both the credential token and the `[realm.global]` binding section. Login therefore materializes `global` as the optional chain tail, after which a single sign-in is inherited by workspace realms without a per-realm re-login. Earlier `dev`-realm logins are migrated to `global` on the run path (one-time, idempotent, no-clobber), so an existing sign-in keeps working without re-auth. Credential **reads inherit** down the realm chain (a child realm resolves a binding defined in a parent or in `global`), but credential **writes are strict-owner**: the caller must explicitly target the realm that defines the binding; a child-addressed inherited write is rejected. `--realm` on profile, status, test, and refresh commands selects the realm and composes its chain for resolution. Logout is different: its positional `[:]` selects the token owner directly, and a bare binding means `global`; `--realm` does not retarget logout. See [Realm inheritance](/concepts/realm-inheritance) and the [auth guide](/guides/auth) for the full model. ## models ```bash theme={null} rkat models ``` This prints the effective runtime model registry for the active realm, including configured `self_hosted` aliases and their `server_id`. ## doctor ```bash theme={null} rkat doctor ``` For self-hosted setups, `doctor` checks the normalized `/v1/models` endpoint for each configured server and warns when configured aliases are missing from the returned model list. For Gemma 4, prefer `chat_completions` in your server config unless you have validated a specific `responses` path for your serving stack. Follow [Self-hosting models](/guides/self-hosting-models) for the full Gemma 4 examples. ## storage Storage administration verbs. All of them dispatch before realm resolution, so they run against the exact on-disk state they diagnose — including split-brain realms the normal resolver refuses. Because no runtime scope is resolved, the global `--isolated` and `--default-model` flags are rejected as usage errors on every storage verb rather than silently ignored; scope the sweep with `--realm`, `--root`, or `--state-root` instead. ```bash theme={null} rkat storage doctor [--json] [--root PATH]... ``` Read-only and safe against a live realm: takes no leases, never changes logical database content, and never creates a database or directory. SQLite may create or update the `-wal`/`-shm` sidecars needed for a coherent WAL read. Sweeps the invocation-context-local (`/.rkat/realms`) and user-global roots by default. Ordinary runtime resolution first walks to the nearest ancestor containing `.rkat`, so run the storage verb from that project root (or pass `--root`) to inspect the same local candidate; any explicit root (`--state-root` or repeatable `--root`) restricts the sweep to exactly those roots. `--realm` focuses the sweep on one realm. Reports per-root realm inventory, schema-ledger state per database, dual-root twins, dangling session→blob references, and orphaned lease/lock/backup artifacts. Exit 0 means no error-severity findings; exit 1 means errors were found. ```bash theme={null} rkat storage migrate [--apply] [--bridge-pre-0-8-10] [--json] [--root PATH]... [--adopt-root PATH] [--fence-wait-secs SECS] ``` `migrate` is dry-run by default, offline, resumable, and fail-closed. It sweeps the same roots (and honors the same `--realm` filter) as `storage doctor`. The dry run reads each realm's schema-ledger baseline read-only — no fence, no store opens, no mutation. `--apply` acquires the realm's exclusive maintenance fence (`--fence-wait-secs`, default 10, bounds the wait for in-flight store operations to drain), then per realm: stamps ledgers by opening every store through its normal constructor under the held fence and reports state-root adoption (report-only — realms are used where they lie). Exact 0.8.10 session-state conversion is owned by each backend's activation transaction, which binds the released schema, key, and source bytes before installing current store authority; `storage migrate` does not bulk-adopt documents or defer conversion to ordinary reads. A realm materialized under multiple swept roots is a fail-closed refusal unless `--apply --adopt-root ` names the swept root whose copy to keep: every copy is fenced first, the divergence report is recomputed under the held fences, and archiving is gated on that comparison being conclusive (an unreadable entry poisons it and refuses) — then every other copy is archived read-only under the registered `*.pre--` backup naming. Divergent data is preserved and reported, never merged. Per-mob databases under `mobs/` are report-only, and credential stores are never read, moved, or reported. Exit 0 = clean; exit 1 = errors or fail-closed refusals (split-brain without `--adopt-root`, unacquirable maintenance fence). `--bridge-pre-0-8-10` is an explicit `--apply`-only maintenance lane for SQLite realms. JSONL and memory realms are rejected before any database is mutated. While the realm fence is held, it runs a frozen importer before the normal store constructors. A domain is authenticated as exactly one caller-authorized source catalog; an unknown or ambiguous catalog refuses that domain instead of being inferred or stamped, and each domain owns its own transaction, so a domain that committed stays committed when a later one refuses. The same authentication answers the eligibility sentence an ordinary open prints, so a realm the bridge recovers is never described as unrecoverable and a realm it cannot recover is never handed this command. Row admission is per record, not per domain. Every runtime input row is carried forward when it decodes through the current typed contract and re-encodes without losing a field; a row that cannot be is left with its bytes exactly as found - never deleted, never blanked - and named in the output with the reason and the consequence. Rows are preserved in the current representation without being scheduled or replayed, and that includes their ingress payloads: a rescued realm keeps the operator's own prompt whatever lifecycle state its input reached. A later session activation follows normal recovery, which applies this binary's ordinary payload retirement to rows it writes itself. Ordinary store opens never enter this bridge. ```bash theme={null} rkat storage prune [--apply] [--older-than-days N] [--json] [--root PATH]... ``` `prune` owns the lifecycle of registered maintenance artifacts only — `*.pre--` migration backups and `*.corrupt-` index quarantines; nothing outside those naming patterns is ever touched. The default run lists artifacts with sizes and ages; `--apply` deletes those at least `--older-than-days` (default 30; 0 = all) days old. Age comes from the timestamp embedded in the registered name, not filesystem mtime — renames preserve mtime, so a long-idle file archived today would otherwise look instantly prunable. `--realm` restricts eligibility to one realm's artifacts. Exit 0 = clean; exit 1 = deletion failures. Not to be confused with `rkat realm prune`, which deletes whole realm directories. ## mcp `rkat mcp` is for local and project configuration only. ```bash theme={null} rkat mcp add [--transport stdio|http|sse] [--scope project|user|local] [-H KEY:VALUE...] [-e KEY=VALUE...] [--url | | -- ] rkat mcp login [--scope project|user|local] rkat mcp remove [--scope project|user|local] rkat mcp list [--scope project|user|local] [--json] rkat mcp get [--scope project|user|local] [--json] ``` Examples: ```bash theme={null} rkat mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem . rkat mcp add api --url https://mcp.example.com/api rkat mcp add --transport http remote https://mcp.example.com/api rkat mcp login remote rkat mcp list rkat mcp get filesystem --scope project ``` Omit `--scope` on `list` or `get` to search all configured scopes. HTTP OAuth is discovered when connecting, not stored in `.rkat/mcp.toml`. Use `rkat mcp login ` to open the browser flow ahead of time, or `rkat run "..." --mcp-auth interactive` to allow a TTY run to authenticate when an HTTP MCP server first requires it. The default `--mcp-auth stored` uses persisted tokens only. ## mob `rkat mob` is the artifact, typed callable run, and operational run-resource surface. Runtime semantics still live in the shared mob runtime; the CLI only binds to it. ```bash theme={null} rkat mob pack -o [--sign --signer-id ] rkat mob inspect rkat mob validate [--trust-policy ] rkat mob run [--flow ] [--param ...] [--prompt ] [--detach] [--json] [--trust-policy ] rkat mob deploy [-m|--model ] [--max-total-tokens ] [-d|--max-duration ] [--max-tool-calls ] [--trust-policy ] [--surface ] rkat mob web build -o --wasm [--trust-policy ] rkat mob run-flow --flow [--params ] [--stream|--no-stream] rkat mob flow-status rkat mob runs [--flow ] [--json] rkat mob status [--json] rkat mob logs [--after-cursor ] [--limit ] [--json] rkat mob attach [--json] rkat mob spawn-helper --agent-identity --result-label