Skip to main content
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:
You can also use subcommands explicitly:

Global flags

All commands accept the same realm and convention-root flags:
--default-model <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 context root, derive a stable workspace realm id from that path, and store realm state under <context-root>/.rkat/realms/<realm>/. --context-root changes both the derived workspace identity and the default project-local state root. --state-root changes only where realm directories are stored. 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:
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

Prompt-first usage

Examples:

Common run flags

  • -m, --model <MODEL>
  • -o, --output <text|json|html>
  • --json
  • -s, --stream
  • --no-stream
  • --no-web-search
  • --resume[=<SESSION>]
  • --skill <PATH_OR_ID> repeatable
  • -d, --max-duration <DURATION>
  • -t, --tools <safe|workspace|full|none>
  • --stdin <auto|blob|lines|off>
  • --keep-alive
  • --wait-for-mcp
  • --mcp-auth <stored|interactive>
  • -v, --verbose
For the full advanced set, use:

Tool presets

rkat uses presets instead of many enable/disable booleans. --yolo is an alias for --tools full.

Provider and structured output controls

Use --param for common tuning and --params-json as the escape hatch:
Structured output is file-friendly:
--json is a convenience alias for --output json. HTML output asks the agent to make the final answer a standalone local HTML artifact:
--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]:
Per run, use --html-template <NAME> or --html-template-file <PATH>. 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:
Live line mode:
--line-format json treats each incoming line as JSON instead of plain text.

run —resume

Examples:
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:

session

This is the human/operator session surface. CLI-internal control-plane session APIs are not exposed here. 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:
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.

config

The positional argument is always a file path; inline payloads use --json (or --toml for set). Examples:

auth

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. Because global is the universal tail of every realm chain, a single sign-in is inherited by every workspace realm, across workspaces, 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: a write targets the realm that defines the binding. --realm on an auth command selects the realm and composes its chain for resolution, without changing where an owned credential is persisted. See Realm inheritance and the auth guide for the full model.

models

This prints the effective runtime model registry for the active realm, including configured self_hosted aliases and their server_id.

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 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.
Read-only and safe against a live realm: takes no leases, opens read-only connections only, creates nothing. Sweeps the project-local (<context-root>/.rkat/realms) and user-global candidate roots by default; 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.
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 <path> 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-<version>-<timestamp> 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. The importer accepts only authenticated, supported pre-floor schema and row shapes; unknown, ambiguous, or inconsistent state refuses instead of being inferred or stamped. The maintenance transaction preserves queued and nonterminal runtime inputs in the current representation without scheduling or replaying them. A later session activation follows normal recovery. Ordinary store opens never enter this bridge.
prune owns the lifecycle of registered maintenance artifacts only — *.pre-<version>-<timestamp> migration backups and *.corrupt-<timestamp> 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.
Examples:
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 <NAME> 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.
Multi-host notes:
  • rkat mob host starts only the signed member-host and optional live listeners. It uses the workspace-derived realm (or explicit --realm) and rejects --isolated; it does not expose an RPC, REST, or MCP console.
  • When enabling the host pairing branch, prefer --pairing-password-env or --pairing-password-file so the secret does not appear in process arguments. The three pairing-secret options are mutually exclusive; --pairing-password remains available for compatibility. Pairing secrets must be at least 32 bytes and are validated before host startup effects. Pairing is accepted only on an IP loopback listener because it returns the one-time binding descriptor over the plaintext comms transport. Use the 0600 descriptor out-of-band for remote hosts, or tunnel a loopback listener.
  • rkat mob bind-host consumes the descriptor JSON written by rkat mob host --descriptor-out; the 0600 descriptor carries a single-use bootstrap token, and the bind report (host id, authority epoch, capability record) prints as JSON.
  • grant, revoke-grant, and grants manage the closed control-scope set: list, read_history, subscribe_events, send_command, cancel, retire, wire_topology, live, admin_host, and admin_grants.
  • rkat mob live open prints the wire LiveOpenResult JSON — including the live URL and single-use token — to stdout only; stderr carries a token-free note. The socket it names is the input plane: there is no live send verb.
  • Mob verbs exit with typed codes for the four multi-host error classes: scope denied 45, host unavailable 46, stale cursor 47, stale fence 48, each with a one-line detail: {...} JSON rendering on stderr. Everything else keeps the generic exit 1.
Examples:

Trust policy

  • --trust-policy strict rejects unsigned packs and unknown signers
  • --trust-policy permissive allows unsigned packs with warnings but still rejects invalid signatures

Web build prerequisites

The CLI does not compile wasm32 itself. --wasm is required and must point at the prebuilt meerkat-web-runtime artifacts — either the wasm-pack --target web output directory (which holds meerkat_web_runtime.js + meerkat_web_runtime_bg.wasm) or that *_bg.wasm file (the sibling .js glue is copied alongside). mob web build copies those artifacts into its output. wasm-pack is one way to generate the required input:
The emitted bundle is self-contained and runnable: serve the output directory and open index.html (it includes the glue, a meerkat-bootstrap.js module, and the mobpack).

skill

workgraph

rkat workgraph provides operator lookup plus narrow goal and attention controls for the active realm.
Agents mutate WorkGraph through workgraph_* tools. The CLI exposes only the narrow trusted goal/attention controls above; attention continuation injection remains runtime-host owned rather than a REST-backed CLI command.

models

Lists all available models grouped by provider, including display name, tier, context window, max output tokens, and profile capabilities (temperature, thinking, reasoning support). Data is compiled from the meerkat-models catalog (injected into meerkat-core as a ModelCatalog).

capabilities

Shows status for compiled/runtime capabilities.

doctor

Checks:
  • config readability
  • common provider API keys
  • MCP config loading
  • wasm-pack availability as one way to generate the required --wasm artifacts; mob web build copies them and does not invoke wasm-pack

init

Creates .rkat/config.toml from the global template.