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

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

```bash theme={null}
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

```bash theme={null}
rkat [OPTIONS] <PROMPT>
rkat run [OPTIONS] <PROMPT>
```

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

```bash theme={null}
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:

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

```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[=<SESSION_ID>] [OPTIONS] <PROMPT>
```

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

```bash theme={null}
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:

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

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

## mcp

`rkat mcp` is for local and project configuration only.

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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.

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
rkat capabilities
```

Shows status for compiled/runtime capabilities.

## doctor

```bash theme={null}
rkat doctor
```

Checks:

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

## init

```bash theme={null}
rkat init
```

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