meerkat-cli-reference

name	meerkat-cli-reference
description	Exact rkat CLI command contract for Meerkat help answers. Use this as the authority for command names, flags, aliases, and negative CLI facts.

Meerkat CLI Reference

Use this skill as the exact authority for rkat shell commands. Command spelling, singular/plural forms, flags, and enum values matter.

Hard Negative Facts

• There is no rkat sessions; use singular rkat session.
• There is no rkat resume; use rkat run --resume ....
• There is no rkat rpc; use the rkat-rpc binary for JSON-RPC.
• rkat-rpc --tcp is not a Meerkat signed peer/comms listener; use rkat run --comms-listen-tcp ... for remote peers and external mob members.
• There is no rkat live; use JSON-RPC live/* with rkat-rpc --live-ws.
• There is no rkat image command.
• There is no rkat mcp reload CLI command.
• There is no --tools all; valid values are safe, workspace, full, none.
• rkat blob get has no -o or --out; use --output <FILE>.
• rkat session show has no --json flag.
• rkat models and rkat capabilities already print pretty JSON and have no --json/--format flags.
• rkat doctor (setup checks, no flags) and rkat storage doctor (storage diagnosis, --json/--root) are different commands.
• rkat storage prune deletes only registered maintenance backup artifacts; realm deletion is rkat realm delete / rkat realm prune.
• --isolated and --default-model cannot be combined with rkat storage; both are usage errors.

Root

rkat [OPTIONS] <PROMPT>      # shorthand for rkat run <PROMPT>
rkat [OPTIONS] <COMMAND>

Global/realm options:

-r, --realm <REALM>
--isolated
--instance <INSTANCE>
--realm-backend <jsonl|sqlite>
--state-root <PATH>
--context-root <PATH>
--user-config-root <PATH>
--default-model <MODEL>

--default-model <MODEL> persists the default agent model into the scope-resolved config (same project/user/realm resolution as every other command) and exits when given without a command, or applies first when combined with one. The model is validated against the catalog and any configured custom models:

rkat --default-model claude-fable-5

Top-level commands:

rkat init
rkat run <PROMPT> [OPTIONS]
rkat help <QUESTION> [OPTIONS]
rkat session list|show|delete|interrupt ...
rkat blob get <BLOB-ID> [--output <FILE>] [--json]
rkat realm current|list|show|create|delete|prune ...
rkat mcp add|login|remove|list|get ...
rkat mob spawn-helper|fork-helper|member-status|force-cancel|respawn|wait-kickoff|run|runs|status|logs|attach|run-flow|flow-status|pack|inspect|validate|deploy|web ...
rkat workgraph list|show|ready|snapshot|events ...
rkat skill add|remove|get|list|inspect ...
rkat config get|set|patch ...
rkat capabilities
rkat models
rkat doctor
rkat storage doctor|migrate|prune ...
rkat auth realms|profiles|profile|profile-delete|bindings|test|status|login|logout|refresh ...

Run

rkat run <PROMPT>
rkat <PROMPT>
rkat run --resume[=<SESSION>] <PROMPT>

Common options:

--resume [<SESSION>]            # omit value to resume last
-m, --model <MODEL>
-d, --max-duration <DURATION>
-o, --output <text|json|html>
--json                          # alias for --output json
-s, --stream
--no-stream
--no-web-search                 # disable provider-native web search for this run
--html                          # alias for --output html
--browser                       # output html and open it in the browser
--open-in-browser               # open HTML output after writing the artifact
--html-template <NAME>
--html-template-file <PATH>
--skill <PATH_OR_ID>            # repeatable
-t, --tools <safe|workspace|full|none>
--yolo                          # alias for --tools full
-v, --verbose
--keep-alive
--stdin <auto|blob|lines|off>

Advanced options:

--system <SYSTEM_PROMPT>
-p, --provider <anthropic|openai|gemini|self-hosted>
--max-tokens <N>
--max-tool-calls <N>
--param <KEY=VALUE>             # repeatable
--params-json <JSON>
--schema <SCHEMA_OR_PATH>
--allow-tool <TOOL>             # repeatable first-turn allow overlay
--block-tool <TOOL>             # repeatable first-turn block overlay
--label <KEY=VALUE>             # repeatable
--instructions <TEXT>           # repeatable
--app-context <JSON>
--wait-for-mcp
--mcp-auth <stored|interactive>
--line-format <text|json>
--auth-binding <REALM:BINDING[:PROFILE]>
--comms-name <NAME>                         # stable signed comms participant name
--comms-listen-tcp <HOST:PORT>              # signed agent-to-agent TCP listener
--comms-advertise-tcp <HOST:PORT>           # advertised signed comms address
--comms-binding-out <PATH>                  # write external mob/runtime binding JSON
--comms-pairing-password <PASSWORD>         # one-time signed comms enrollment password
--comms-pairing-password-env <ENV>          # read enrollment password from env
--comms-pairing-password-file <PATH>        # read enrollment password from file
--agent-description <TEXT>
--agent-label <KEY=VALUE>                   # repeatable peer metadata
--no-comms                                  # disables comms runtime/tools

Remote signed peer example:

rkat run \
  --comms-name remote-worker \
  --comms-listen-tcp 0.0.0.0:4200 \
  --comms-advertise-tcp worker.example.com:4200 \
  --comms-binding-out ./remote-worker.binding.json \
  --keep-alive \
  "You are a remote worker."

--comms-listen-tcp, --comms-advertise-tcp, --comms-binding-out, and pairing password flags cannot be combined with --no-comms. Use only one pairing password source. The generated binding has kind: "external", advertised address, Ed25519 public identity, and typed bootstrap_token.

Resume targets: full UUID, UUID prefix/tail handle, realm:<uuid>, last, ~, ~0, or ~N.

Defaults:

• --tools safe
• default model is OpenAI gpt-5.6-sol unless realm config/auth binding selects another model; Sol is a limited preview, so configure gpt-5.5 when the relevant API organization or Codex workspace lacks access
• current recommended Gemini model is gemini-3.5-flash
• CLI realm state is project-local by default: <context-root>/.rkat/realms/<ws-...>/; that head realm's config composes over its parent chain and the HOME-rooted global doc (~/.rkat/config.toml)
• stream on in a TTY, off in pipes/scripts
• piped stdin is blob context unless --stdin lines
• short session handles are UUID tails; resume accepts full UUID, prefix/tail, realm:<uuid>, last, ~, or ~N

Help

rkat help <QUESTION>
rkat help <QUESTION> --prompt <PROMPT> --plan-execution

Options: --prompt, --plan-execution, -m/--model, -p/--provider, --max-tokens, -o/--output, --json, -s/--stream, --no-stream, plus global/realm options.

Image Generation Via CLI

Image generation is assistant-mediated. Ask through rkat run, allow the image tool, and fetch the returned blob id:

rkat run --allow-tool generate_image "Use generate_image to create a 1024x1024 PNG of a red fox in snow. Return the blob id."
rkat blob get <BLOB-ID> --output fox.png

If the assistant did not print the blob id, resume the same session and ask for the blob id. Do not use rkat sessions show --json, rkat rpc blob/get, or rkat blob get -o.

Session

rkat session list [--limit N] [--offset N] [--label KEY=VALUE]
rkat session show <ID>
rkat session delete <ID>
rkat session interrupt <ID>

rkat session show is human-readable and has no --json.

Blob

rkat blob get <BLOB-ID> [--output <FILE>] [--json]

--output writes raw bytes to a file. --json prints the blob payload as JSON. blob get requires an existing blob id; it does not discover blob ids.

MCP

rkat mcp add <NAME> [--transport stdio|http|sse] [--scope project|user|local] [-H KEY:VALUE...] [-e KEY=VALUE...] [--url <URL> | <URL> | -- <CMD...>]
rkat mcp login <NAME> [--scope project|user|local]
rkat mcp remove <NAME> [--scope project|user|local]
rkat mcp list [--scope project|user|local] [--json]
rkat mcp get <NAME> [--scope project|user|local] [--json]

Omit --scope on list/get to search all scopes. Do not pass --scope all. Live mutation of an already-running session uses RPC/REST/MCP/SDK surfaces, not rkat mcp reload.

For streamable HTTP OAuth, rkat mcp add remains simple: no auth schema is stored in MCP config. Use rkat mcp login <name> for explicit browser login. rkat run defaults to stored MCP OAuth tokens; use --mcp-auth interactive to allow first-use browser auth and reconnect in a TTY run.

Realm

rkat realm current
rkat realm list
rkat realm show <REALM_ID>
rkat realm create <REALM_ID> [--backend jsonl|sqlite]
rkat realm delete <REALM_ID> [--force]
rkat realm prune [--isolated-only] [--older-than-hours N] [--force]

A realm is a config + state namespace. The reserved realm slug global is the universal default head of every realm chain; its config is the single HOME-rooted doc at ~/.rkat/config.toml. A realm config doc may declare a parent in its own section:

[realm.team]
parent = "global"
# ... default_binding, [realm.team.backend.*], [realm.team.binding.*], etc.

Resolution walks the head realm to its parent chain to the implicit global tail (depth-capped, fail-closed; no flat sibling scan, no literal default realm). CONFIG inherits down the chain: models, mcp servers, hooks, skills, limits, and auth bindings. STATE never inherits: sessions, SQLite/JSONL stores, and event stores are realm-LOCAL. Children may ADD or OVERRIDE inherited mcp/hook entries but cannot REMOVE them (no tombstones). rkat config get/set operate on the RAW head realm doc (read/write split), so an inherited entry is never flattened into a child doc; a write to an inherited binding is rejected as strict-owner.

Live channels

There is no rkat live CLI group. Live channels are controlled through JSON-RPC live/open, live/status, live/close, live/send_input, live/commit_input, live/interrupt, live/truncate, and live/refresh. Start rkat-rpc with --live-ws <ADDR> for the WebSocket transport.

Mob

Direct rkat mob is helper/artifact/run-resource oriented. Lifecycle creation, wiring, and member management are done with agent mob_* tools or RPC mob/*.

rkat mob spawn-helper <mob_id> <prompt> --agent-identity <id> [--profile <profile>] [--json]
rkat mob fork-helper <mob_id> <source_member> <prompt> --agent-identity <id> [--profile <profile>] [--fork-context full-history|last-messages] [--last-messages N] [--json]
rkat mob member-status <mob_id> <agent_identity> [--json]
rkat mob force-cancel <mob_id> <agent_identity>
rkat mob respawn <mob_id> <agent_identity> [--initial-message <MSG>]
rkat mob wait-kickoff <mob_id> [--member <agent_identity>...] [--timeout-ms N] [--json]
rkat mob run <pack_or_mob_id> [--flow <flow_id>] [--param key=value ...] [--prompt <text>] [--detach] [--json] [--trust-policy permissive|strict]
rkat mob runs <mob_id> [--flow <flow_id>] [--json]
rkat mob status <mob_id> <run_id> [--json]
rkat mob logs <mob_id> [--after-cursor N] [--limit N] [--json]
rkat mob attach <mob_id> <run_id> [--json]
rkat mob run-flow <mob_id> --flow <flow_id> [--params <json>] [-s|--stream] [--no-stream]
rkat mob flow-status <mob_id> <run_id>
rkat mob pack <dir> -o <pack> [--sign <key> --signer-id <id>]
rkat mob inspect <pack>
rkat mob validate <pack> [--trust-policy permissive|strict]
rkat mob deploy <pack> <prompt> [--model <model>] [--max-total-tokens N] [--max-duration D] [--max-tool-calls N] [--trust-policy permissive|strict] [--surface cli|rpc]
rkat mob web build <pack> -o <dir> --wasm <PKG_DIR|name_bg.wasm> [--trust-policy permissive|strict]

Packing with --sign embeds the signer identity and public key but does not install that signer in a trust store. For a locally signed pack whose signer is not installed, use the explicit permissive posture (signature verification still runs and reports an unknown-signer warning):

rkat mob validate ./dist/release-triage.mobpack --trust-policy permissive
rkat mob run ./dist/release-triage.mobpack --flow main --trust-policy permissive
rkat mob web build ./dist/release-triage.mobpack -o ./dist/release-triage-web --wasm <PKG_DIR|name_bg.wasm> --trust-policy permissive

For rkat run prompts that need mob_* tools, use --tools full or config that enables mob tools.

Skill

rkat skill add <PATH> [--name <NAME>]
rkat skill remove <NAME_OR_SOURCE_UUID_OR_PATH>
rkat skill get <NAME_OR_SOURCE_UUID_OR_PATH> [--json]
rkat skill list [--json]
rkat skill inspect <SKILL_NAME> --source-uuid <SOURCE_UUID> [--json]

skill add takes a filesystem path, not an arbitrary skill id.

Config

rkat config get [--format toml|json] [--with-generation]
rkat config set [FILE] [--json <JSON> | --toml <TOML>] [--expected-generation <N>]
rkat config patch [FILE | --json <JSON>] [--expected-generation <N>]

set <FILE> imports a file into the active realm config. Raw JSON merge patch uses rkat config patch --json '{...}'. config get/set/patch use the RAW head realm doc (read/write split): they show and write only the head realm's own fields, never the chain-composed effective config — so a read-modify-write cannot flatten inherited mcp/hook/skill/binding entries into the head doc. Inherited config is composed only on the agent-build path.

Models And Capabilities

rkat models
rkat capabilities

Both commands print pretty JSON by default. Neither accepts --json or --format.

rkat models prints the effective runtime model registry for the active realm: built-in catalog entries plus configured self_hosted aliases.

Doctor

rkat doctor

No doctor-specific flags. Output is tab-delimited ok|warn <area> <message>. Hard config/MCP/self-hosted issues exit 1; missing provider env vars and missing wasm-pack are warnings. Storage diagnosis is the separate rkat storage doctor.

Storage

Offline storage administration. All three verbs dispatch BEFORE runtime-scope resolution: they take no realm leases and create no realm — so they run against split-brain realms the normal resolver refuses. Doctor, prune, and migrate's default dry run open no persistence bundle; migrate --apply does open each swept realm's bundle (under the exclusive maintenance fence) to stamp ledgers and run bulk checkpoint adoption. --isolated and --default-model are usage errors with rkat storage; scope the sweep with --realm/--root instead.

rkat storage doctor [--json] [--root <PATH>]...
rkat storage migrate [--apply] [--json] [--root <PATH>]... [--adopt-root <PATH>] [--fence-wait-secs <SECS>]
rkat storage prune [--apply] [--older-than-days <DAYS>] [--json] [--root <PATH>]...

Sweep roots (all three verbs): by default the invocation directory's project-local candidate (<context-root>/.rkat/realms) and the user-global data root. Note the runtime resolver additionally walks UP from the invocation context to the project root before forming its local candidate — run storage verbs from the project root (or pass --root) to sweep the same location the runtime resolves. When any explicit root is given (the global --state-root or one or more repeatable --root), ONLY those roots are read. The global -r/--realm restricts the sweep to one realm id (split-brain twins for it are still detected across all swept roots).

storage doctor is read-only and safe against live realms: takes no leases, opens databases read-only, creates nothing. Reports per-root realm inventory, manifest state, schema-ledger versions per database, dual-root split-brain twins, a checkpoint-evidence census (verified vs legacy-unverified sessions), dangling session→blob references, and orphaned lock/lease/backup artifacts. Exit 0 = no error-severity findings; exit 1 = errors found.

storage migrate is the offline migration framework, dry-run by default; --apply runs the fenced migration. Per realm: (1) ledger baseline — under the realm's exclusive maintenance fence (--fence-wait-secs, default 10, bounds the in-flight-operation drain wait), every store opens through its normal constructor so guarded schema-ledger migrations converge files of any vintage; (2) state-root adoption — report-only, realms are used where they lie; (3) split-brain reconciliation — a realm id under 2+ swept roots is a fail-closed refusal unless --apply --adopt-root <PATH> names the swept root to keep, in which case every other copy is archived read-only under the registered *.pre-<version>-<timestamp> backup naming (no merging, no synthesis); (4) checkpoint-evidence adoption — bulk machine-owned stamping of legacy pre-typed session checkpoints (sqlite realms; jsonl realms heal lazily and are reported as skipped); (5) deprecated leftovers — report-only. --adopt-root without --apply is a usage error. Credential stores are never read, moved, or reported. Exit 1 = errors or fail-closed refusals (including split-brain without --adopt-root and an unacquirable maintenance fence).

storage prune manages registered maintenance artifacts ONLY: *.pre-<version>-<timestamp> migration backups (files or archived realm directories) and *.corrupt-<timestamp> index quarantines. Dry-run by default (lists artifacts with sizes and ages); --apply deletes those at least --older-than-days old (default 30; 0 = all). Age comes from the timestamp embedded in the registered artifact name, not filesystem mtime. Nothing outside the registered naming patterns is ever touched. Unrelated to rkat realm prune, which deletes live realms.

Auth

rkat auth realms
rkat auth profiles
rkat auth profile <PROFILE_ID>
rkat auth profile-delete <PROFILE_ID> [-y|--yes]
rkat auth bindings
rkat auth test <BINDING_ID>
rkat auth status <PROFILE_ID>
rkat auth login [PROVIDER] [--backend <BACKEND>] [--method <METHOD>] [--non-interactive --secret <SECRET>]
rkat auth logout <PROFILE_ID>
rkat auth refresh <PROFILE_ID>

rkat auth login <provider> provisions the reserved global realm in the HOME-rooted doc (~/.rkat/config.toml), so one sign-in is inherited by every workspace realm via the chain tail (cross-workspace). Interactive OAuth writes global:anthropic_oauth, global:openai_oauth, or global:google_oauth; non-interactive api-key login writes global:default_<provider>. Legacy logins persisted under dev; on the run path those credentials and the [realm.global] binding section migrate to global once (idempotent, no-clobber), so an existing sign-in keeps working without re-login. There is no dev default anymore.

rkat auth realms lists every configured realm section; rkat auth status, test, refresh, and logout are binding-scoped (AuthMachine leases are binding-scoped). Credential READS inherit down the chain (a child realm resolves a binding defined in a parent or in global); a resolved binding's reported owning realm is the realm that DEFINES it, not the requesting realm. Credential WRITES are strict-owner: auth login and config writes land only in the realm that OWNS the binding — you cannot write into an inherited realm's doc from a child.

Runtime env fallback order:

• Anthropic: RKAT_ANTHROPIC_API_KEY, ANTHROPIC_API_KEY
• OpenAI: RKAT_OPENAI_API_KEY, OPENAI_API_KEY
• Gemini: RKAT_GEMINI_API_KEY, GEMINI_API_KEY, RKAT_GOOGLE_API_KEY, GOOGLE_API_KEY
• Azure OpenAI: RKAT_AZURE_OPENAI_API_KEY + RKAT_AZURE_OPENAI_ENDPOINT, then AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT

WorkGraph

rkat workgraph is operator lookup plus narrow goal/attention control for the active realm. Agents mutate ordinary WorkGraph items through workgraph_* tools.

rkat workgraph list [--namespace <NS>] [--all-namespaces] [--status <STATUS>] [--label <LABEL>] [--include-terminal] [--limit <N>] [--json]
rkat workgraph show <ID> [--namespace <NS>] [--json]
rkat workgraph ready [--namespace <NS>] [--label <LABEL>] [--limit <N>] [--json]
rkat workgraph snapshot [--namespace <NS>] [--all-namespaces] [--status <STATUS>] [--label <LABEL>] [--include-terminal] [--limit <N>] [--json]
rkat workgraph events [--namespace <NS>] [--all-namespaces] [--after-seq <N>] [--limit <N>] [--json]
rkat workgraph goal-create <SESSION_ID> <TITLE> [--namespace <NS>] [--description <TEXT>] [--mode pursue|coordinate|review|falsify|judge|observe] [--completion-policy self-attest|host-confirmed] [--json]
rkat workgraph goal-status <BINDING_ID> [--namespace <NS>] [--json]
rkat workgraph goal-confirm <BINDING_ID> --expected-revision <N> --kind <KIND> --id <ID> [--namespace <NS>] [--label <TEXT>] [--summary <TEXT>] [--json]
rkat workgraph goal-close <BINDING_ID> --expected-revision <N> [--namespace <NS>] [--status completed|cancelled|failed] [--json]
rkat workgraph attention-list [--namespace <NS>] [--status active|paused|stopped|superseded] [--json]
rkat workgraph attention-pause <BINDING_ID> --expected-revision <N> [--namespace <NS>] [--json]
rkat workgraph attention-resume <BINDING_ID> --expected-revision <N> [--namespace <NS>] [--json]