CLI commands - Meerkat

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:

rkat "summarize this repository"

You can also use subcommands explicitly:

rkat run "summarize this repository"
rkat run --resume last "keep going"
rkat mob pack ./mobs/release-triage -o dist/release-triage.mobpack

Global flags

All commands accept the same realm and convention-root flags:

rkat [--realm <id>] [--isolated] [--instance <id>] \
  [--realm-backend <sqlite|jsonl|memory>] \
  [--state-root <path>] \
  [--context-root <path>] \
  [--user-config-root <path>] \
  [--default-model <model>] \
  <command>

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

Common commands

Command	Purpose
`rkat <PROMPT>`	Run a task directly from the terminal
`rkat run <PROMPT>`	Explicit form of the default prompt command
`rkat run --resume[=<SESSION>] <PROMPT>`	Continue a saved session
`rkat help <QUESTION>`	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 init`	Create project config from the global template

Prompt-first usage

rkat [OPTIONS] <PROMPT>
rkat run [OPTIONS] <PROMPT>

Examples:

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

rkat run --help

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:

rkat -m claude-sonnet-4-6 \
  --param temperature=0.2 \
  --param max_output_tokens=4000 \
  "triage this incident"

Structured output is file-friendly:

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:

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

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

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:

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

rkat run --resume[=<SESSION_ID>] [OPTIONS] <PROMPT>

Examples:

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:

rkat run --resume -m gemma-4-31b "Continue with the local model"

session

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

This is the human/operator session surface. CLI-internal control-plane session APIs are not exposed here.

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

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

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"}}}}'

models

rkat models

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

doctor

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 for the full Gemma 4 examples.

mcp

rkat mcp is for local and project configuration only.

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]

Examples:

rkat mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
rkat mcp add linear --url https://mcp.example.com
rkat mcp add --transport http glean https://king-be.glean.com/mcp/default
rkat mcp login glean
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 <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.

rkat mob pack <DIR> -o <OUT.mobpack> [--sign <KEY_FILE> --signer-id <ID>]
rkat mob inspect <PACK.mobpack>
rkat mob validate <PACK.mobpack>
rkat mob run <PACK.mobpack|MOB_ID> [--flow <FLOW_ID>] [--param <KEY=VALUE>...] [--prompt <TEXT>] [--detach] [--json]
rkat mob deploy <PACK.mobpack> <PROMPT> [--trust-policy <permissive|strict>] [--surface <cli|rpc>]
rkat mob web build <PACK.mobpack> -o <OUT_DIR> --wasm <PKG_DIR|name_bg.wasm>
rkat mob run-flow <MOB_ID> --flow <FLOW_ID> [--params <JSON>] [--stream|--no-stream]
rkat mob flow-status <MOB_ID> <RUN_ID>
rkat mob runs <MOB_ID> [--flow <FLOW_ID>] [--json]
rkat mob status <MOB_ID> <RUN_ID> [--json]
rkat mob logs <MOB_ID> [--after-cursor <CURSOR>] [--limit <N>] [--json]
rkat mob attach <MOB_ID> <RUN_ID> [--json]
rkat mob spawn-helper <MOB_ID> <PROMPT> --agent-identity <ID> [--profile <PROFILE>] [--json]
rkat mob fork-helper <MOB_ID> <SOURCE_MEMBER_ID> <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 <MESSAGE>]
rkat mob wait-kickoff <MOB_ID> [--member <AGENT_IDENTITY>...] [--timeout-ms <MS>] [--json]

Examples:

rkat mob pack ./mobs/release-triage -o dist/release-triage.mobpack
rkat mob inspect dist/release-triage.mobpack
rkat mob validate dist/release-triage.mobpack
rkat mob run dist/release-triage.mobpack --prompt "triage the latest release regressions"
rkat mob run release-triage --flow main --param severity='"high"' --detach
rkat mob attach release-triage <RUN_ID>
rkat mob web build dist/release-triage.mobpack -o dist/release-triage-web --wasm sdks/web/wasm

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). Use the committed sdks/web/wasm, or build it:

cargo install wasm-pack
wasm-pack build meerkat-web-runtime --target web --out-dir sdks/web/wasm

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

rkat skill add <PATH_OR_ID> [--name <NAME>]
rkat skill remove <NAME_OR_ID_OR_PATH>
rkat skill get <NAME_OR_ID_OR_PATH> [--json]
rkat skill list [--json]
rkat skill inspect <skill-name> --source-uuid <uuid> [--json]

workgraph

rkat workgraph provides operator lookup plus narrow goal and attention controls for the active realm.

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 <MODE>] [--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> [--status completed|cancelled|failed] [--namespace <NS>] [--json]
rkat workgraph attention-list [--namespace <NS>] [--status <STATUS>] [--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]

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

rkat 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

rkat capabilities

Shows status for compiled/runtime capabilities.

doctor

rkat doctor

Checks:

config readability
common provider API keys
MCP config loading
wasm-pack availability for mob web build

init

rkat init

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

​Global flags

​Common commands

​Prompt-first usage

​Common run flags

​Tool presets

​Provider and structured output controls

​Streaming defaults

​Stdin modes and Unix pipes

​run —resume

​session

​config

​models

​doctor

​mcp

​mob

​Trust policy

​Web build prerequisites

​skill

​workgraph

​models

​capabilities

​doctor

​init

Global flags

Common commands

Prompt-first usage

Common run flags

Tool presets

Provider and structured output controls

Streaming defaults

Stdin modes and Unix pipes

run —resume

session

config

models

doctor

mcp

mob

Trust policy

Web build prerequisites

skill

workgraph

models

capabilities

doctor

init