---
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.

## Root

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

Global/realm options:

```bash
-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:

```bash
rkat --default-model claude-fable-5
```

Top-level commands:

```bash
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 auth realms|profiles|profile|profile-delete|bindings|test|status|login|logout|refresh ...
```

## Run

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

Common options:

```bash
--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:

```bash
--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:

```bash
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.5` unless realm config/auth binding selects another model
- 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

```bash
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:

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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:

```toml
[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/*`.

```bash
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> [--trust-policy permissive|strict]
```

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

## Skill

```bash
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

```bash
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

```bash
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

```bash
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.

## Auth

```bash
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.

```bash
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]
```
