> ## 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 "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>] \
  [--state-root <path>] \
  [--context-root <path>] \
  [--user-config-root <path>] \
  <command>
```

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 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`
* `-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 "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>] [--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]
rkat config set <FILE>
rkat config patch <JSON_OR_FILE>
```

Examples:

```bash theme={null}
rkat config get --format toml
rkat config set ./.rkat/config.toml
rkat config patch '{"agent":{"model":"gpt-5.5"}}'
rkat config patch '{"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> | -- <CMD...>)
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 --transport http --url https://mcp.example.com
rkat mcp list
rkat mcp get filesystem --scope project
```

Omit `--scope` on `list` or `get` to search all configured scopes.

## mob

`rkat mob` is the artifact and deployment surface, not a manual runtime-control console.

```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 deploy <PACK.mobpack> <PROMPT> [--trust-policy <permissive|strict>] [--surface <cli|rpc>]
rkat mob web build <PACK.mobpack> -o <OUT_DIR>
rkat mob run-flow <MOB_ID> --flow <FLOW_ID> [--params <JSON>] [--stream|--no-stream]
rkat mob flow-status <MOB_ID> <RUN_ID>
rkat mob spawn-helper <MOB_ID> <PROMPT> [--profile <PROFILE>] [--agent-identity <ID>] [--json]
rkat mob fork-helper <MOB_ID> <SOURCE_MEMBER_ID> <PROMPT> [--profile <PROFILE>] [--agent-identity <ID>] [--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 deploy dist/release-triage.mobpack "triage the latest release regressions"
rkat mob web build dist/release-triage.mobpack -o dist/release-triage-web
```

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

```bash theme={null}
cargo install wasm-pack
wasm-pack --version
```

Optional overrides:

* `RKAT_WASM_PACK_BIN`
* `RKAT_WEB_RUNTIME_CRATE_DIR`

## 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` is read-only operator lookup 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]
```

Agents mutate WorkGraph through `workgraph_*` tools. CLI does not expose write
verbs in v1.

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

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