---
title: "CLI commands"
description: "Command reference for the task-first, Unix-native rkat CLI."
icon: "terminal"
---

`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
rkat "summarize this repository"
```

You can also use subcommands explicitly:

```bash
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
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
rkat [OPTIONS] <PROMPT>
rkat run [OPTIONS] <PROMPT>
```

Examples:

```bash
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
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
rkat -m claude-sonnet-4-6 \
  --param temperature=0.2 \
  --param max_output_tokens=4000 \
  "triage this incident"
```

Structured output is file-friendly:

```bash
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
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
[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
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
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
rkat run --resume[=<SESSION_ID>] [OPTIONS] <PROMPT>
```

Examples:

```bash
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
rkat run --resume -m gemma-4-31b "Continue with the local model"
```

## session

```bash
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
rkat config get [--format toml|json]
rkat config set <FILE>
rkat config patch <JSON_OR_FILE>
```

Examples:

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

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

## doctor

```bash
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
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
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
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
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
cargo install wasm-pack
wasm-pack --version
```

Optional overrides:

- `RKAT_WASM_PACK_BIN`
- `RKAT_WEB_RUNTIME_CRATE_DIR`

## skill

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

Shows status for compiled/runtime capabilities.

## doctor

```bash
rkat doctor
```

Checks:

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

## init

```bash
rkat init
```

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