Skip to main content
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:
You can also use subcommands explicitly:

Global flags

The top-level parser exposes the same realm and convention-root flags to each command family:
The --confinement flags select the OS process confinement of the shell, command hooks and MCP stdio servers this invocation launches, replacing the [confinement] config section for every launch kind; see OS process confinement. --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. In a governed realm (see realm), --as-agent <agent> acts as that agent: its executor and the grants the operator selected for it. The default agent is rkat-agent. By default, CLI commands use the current directory as the invocation context and derive a stable workspace realm id from that path. For project-local state, StorageLayout walks upward to the nearest ancestor containing a .rkat entry and stores realms under <project-root>/.rkat/realms/<realm>/. When no ancestor contains .rkat, the context root is the project root fallback. --context-root changes the derived workspace identity and the starting point for that ancestor search; it does not necessarily change the project root when both contexts are inside the same project. --state-root bypasses discovery and changes only where realm directories are stored. Some maintenance or host commands reject combinations that have no safe meaning. In particular, storage verbs reject --isolated and --default-model, and rkat mob host rejects --isolated. Fresh prompt-first runs and rkat help are fail-soft only at the default workspace storage boundary. If the workspace-derived realm cannot be opened, no historical session from that realm is loaded into the fresh run, and the explicit compatibility bridge is never invoked automatically. The ordinary strict open may already have completed supported manifest initialization or an earlier domain migration before a later store refuses. The CLI warns and creates a new generated realm using durable SQLite under the same resolved state root. The workspace’s configuration, auth policy, provider selection, and tool policy remain in force; only persistence-owned state is isolated in the generated realm. The warning names both realms and prints the explicit recovery command:
An explicit --realm, --isolated, every resume form, and all session commands remain fail-closed. Historical session access therefore stays an explicit maintenance operation. The fresh-run fallback is never an in-memory session and never makes a historical session from the failed workspace realm part of the new run.

Common commands

Prompt-first usage

Examples:

Common run flags

  • -m, --model <MODEL>
  • -o, --output <text|json|html>
  • --json
  • -s, --stream
  • --no-stream
  • --no-web-search
  • --export-atif (write an ATIF trajectory to the realm trajectories/ directory after the turn, with one metered step per provider request: each tool-call turn, the answer, and each structured-output extraction request; default off)
  • --resume[=<SESSION>]
  • --skill <BUILTIN_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
With --stream or --verbose, rkat run prints one token line per provider request (N tokens (I in / O out, C cached, R reasoning), extraction requests labelled extraction:) and closes with total:, the run’s own run_usage. Input counts are presented input, so cached input is included on every provider. Before exiting, rkat run waits for the session event log (.rkat/sessions/<id>/events.jsonl and the realm event store) to finish writing and warns on stderr if it cannot. For the full advanced set, use:
Current CLI help labels this value PATH_OR_ID, but rkat run --skill and resume currently construct builtin skill keys. Direct local-path preload is therefore unsupported. rkat skill add <PATH> registers a filesystem source but does not make this flag source-aware, and ordinary CLI sessions do not currently advertise the skill-discovery tool set. Use typed RPC/SDK preload fields when a host must address a source UUID directly.

Tool presets

rkat uses presets instead of many enable/disable booleans. --yolo is an alias for --tools full.
--tools none is not a universal tool prohibition or sandbox. Configured external MCP tools can still be loaded, and categories such as WorkGraph, mob, schedule, and comms have independent configuration/composition controls. Provider-native capabilities and image generation also have separate controls; the preset does not globally deny their use.

Provider and structured output controls

Use --param for common tuning and --params-json as the escape hatch:
--reasoning-effort <LEVEL> sets the provider-neutral reasoning effort of the session: none, minimal, low, medium, high, xhigh or max. Meerkat checks the level against the model on the route that serves the request and writes the provider’s own field; a level the model or route does not accept is refused before any provider request with exit status 2. It composes with tools, --schema and --stream, and --output json reports what was sent in the result’s reasoning_effort block:
On --resume the flag changes the session’s level from that turn on, --no-reasoning-effort removes it, and neither keeps the level the session recorded:
--param reasoning_effort=high is the same setting; a command that gives both must give the same level. Otherwise the command exits 2 (an invalid request), and with --output json its failure document has the code INVALID_PARAMS. Structured output is file-friendly:
--json is a convenience alias for --output json. With JSON output, stdout ends with exactly one JSON document: the run result when the run succeeds, the pending document ("status": "pending_tool_call") when it stops to wait for an external tool result, or the failure document ({"error": {...}}) when it fails. A script reads the document’s top-level keys, not whether stdout is empty: a failed run writes to stdout too. Exit statuses are the same in every output mode, and stderr still carries the Error: line. With --stream, the streamed text comes first and the document last. rkat has no JSON-lines event output. HTML output asks the agent to make the final answer a standalone local HTML artifact:
--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. The Config schema accepts template defaults under [presentation.html]:
However, ordinary CLI realm composition currently drops the presentation section. On that path, the accepted config above does not supply a custom default or named template to the HTML resolver. This is a composition limitation, not a limitation of direct Rust consumers of a parsed Config. Use the builtin template or a file read directly by the run command:
--html-template-file bypasses configured-template lookup. HTML output itself remains available.

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; input that has not started within 2 s is skipped with a warning, so an open, silent stdin never blocks the run
  • blob: always read full stdin to EOF before running, however long the producer takes to start
  • lines: keep stdin open and process one line at a time
  • off: ignore stdin even if something is piped in
Batch blob mode:
Live line mode:
--line-format json treats each incoming line as JSON instead of plain text.

run —resume

Examples:
SESSION_ID accepts:
  • a full UUID
  • a bare UUID prefix or tail handle
  • <realm>:<uuid>, where <realm> matches the active realm
  • last, ~, or ~0 for the most recent session
  • ~N for the Nth older session (~1 is one before the most recent)
Omitting the value means last, so rkat run --resume "keep going" and rkat run --resume last "keep going" are equivalent. When --resume is followed by the run’s only positional argument, that argument is the prompt and the session is last. A lone argument that names a session (a UUID, <realm>:<uuid>, a hexadecimal handle of 8 to 36 characters, last, ~, or ~N) is read as the session instead, and the prompt is still required. Option values, such as gpt-5.5 in -m gpt-5.5, are not positional arguments. The CLI displays short handles as the final eight UUID characters. Ambiguous prefix/tail matches fail instead of selecting a session. A qualified locator does not switch realms: select the matching realm and storage root first. Relative aliases and short-handle lookup require session-store support. Quote tilde aliases so the shell does not expand them. Resume supports the same stdin model as run, plus per-turn tool overlays and provider params. Self-hosted aliases work the same way:

session

This is the human/operator session surface. CLI-internal control-plane session APIs are not exposed here. session export-atif reads the currently available event audit/replay projection. A slow live subscriber can receive a typed stream-truncation marker without dropping projector input, but projection is asynchronous best-effort derived state and export does not first drain it to the latest committed session boundary. session repair-wholeblob diagnoses, and with --apply repairs, a WholeBlob session whose every send reports reload_required; see Storage operations. session resolve-held-tail reports why durable-tail recovery holds a session’s tail as ambiguous (tail_held_for_recovery), or holds an interrupted tail beside inputs another run left staged or queued (a shape only pre-release builds of 0.9.5, or a store fault, leave), and what the repair keeps, answers, ends and requeues. With --apply it commits a repair the runtime machine authorizes as an interrupted run. Stop every host of the session first: the repair is refused while the persisted lifecycle row is not quiescent, and an idle live host is not detected. A row a host left Stopped when it ended before unregistering (no current run, no unregister in progress) counts as the Idle row a start would normalize it to: the report says so, and --apply writes it with the repair. The command never retries. See Storage operations. Meerkat supports ordinary durable-state opens from 0.8.10 onward. For an older SQLite realm, stop every process that can access it and run the explicit current maintenance bridge:
The frozen importer fails closed on unsupported pre-floor shapes. Normal realm opens remain strict. JSONL and memory realms are rejected before any database is mutated. The maintenance transaction preserves queued and nonterminal input rows without scheduling or replaying them. A later session activation follows normal recovery.

blob

Without either output flag, blob get writes the decoded raw bytes to stdout. --output writes those bytes to a file. --json prints the complete BlobPayload (blob_id, media_type, and base64 data) instead of raw bytes. Blob IDs are realm-scoped, so use the same realm that produced the session or artifact reference.

realm

realm current prints the realm selected by the CLI scope. realm list and realm show inspect manifests in the active state root. realm prune defaults to a 24-hour age threshold. --force bypasses active-lease safety checks, so use it only after confirming that no process still owns the target realm. Neither command removes a realm that another realm’s own config document names as its parent, --force included: the refusal (or prune’s kept_parents note) names the child, which would otherwise stop composing the parent’s [confinement] and [governance]. Nor does either remove a realm an admission holds: both take the realm’s admission fence first, without waiting and before the lease check, and hold it through the removal. realm delete then exits 58, --force included (it overrides heartbeat leases only), and realm prune keeps the realm, counted as active. realm govern makes an existing realm governed, durably, with the local user as operator; every later rkat process opens it governed, and no flag selects that posture. realm grant then issues a named agent (default rkat-agent) one grant per target: an installed MCP server and its raw operations (--mcp <server>=<op>[,<op>...], or <server>=* for all of them), the tool catalog (--catalog), or the agent’s controller (--controller with one or more --route <key>; a controller grant has no expiry). A new grant supersedes only its target’s previous one. In a governed realm rkat attaches a configured MCP server only when it is the realm’s own installation (rkat mcp add --scope realm) with an operation ceiling (--allow-operation). A server from mcp.toml, one the realm inherits from a parent, and an installation without a ceiling are refused before the server is started (attachment authority is unavailable), and their tools are not offered. Install the server with its ceiling first, then grant it (realm grant --mcp): a grant for a server that is not one of the realm’s own installations is refused. Both steps work when the realm is already governed. In a script, check the exit code of each rkat realm command: after a failed realm govern the realm may not be governed, and the commands that follow then run against an ordinary realm. realm revoke-grant revokes the grant selected for one target and exits successfully only when it is revoked. Use the global --as-agent to run as a granted agent. realm govern, grant and revoke-grant take the realm’s admission fence first, waiting up to 5 s for an admission that holds it: past that they exit 58, and 59 when the fence cannot be used, with nothing written.

config

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

auth

rkat auth profile prints the profile’s id, provider, auth_method and source_kind as JSON, the auth_profile shape JSON-RPC auth/profile/get returns. It never prints a credential value: not an inline_secret source’s secret, nor a command source’s arguments or environment values. <PROVIDER> is anthropic, openai, gemini, or copilot (GitHub Copilot: the device sign-in interactively, a GitHub token with --non-interactive; see GitHub Copilot with a service-account token). connector-client manages the realm’s connector OAuth clients: writes go to the realm’s own config, and client secrets go to the credential store, read from stdin and never from the command line. Interactive OAuth/device rkat auth login writes nonsecret backend, auth profile, and binding declarations into the reserved global config doc at ~/.rkat/config.toml. Secret tokens are stored separately through TokenStore. The stock CLI uses <platform-config>/meerkat/credentials/global/<credential-stem>.json, where the platform config directory comes from dirs::config_dir(); files are created with mode 0600 on Unix. --user-config-root changes the config document location, not this TokenStore root. Custom hosts can select a keyring or another store. Interactive login therefore materializes global as the optional chain tail, after which a single sign-in is inherited by workspace realms without a per-realm re-login. Earlier dev-realm logins are migrated to global on the run path (one-time, idempotent, no-clobber), so an existing sign-in keeps working without re-auth. --backend and --method are accepted but ignored during interactive login; the provider determines its OAuth/device flow. In --non-interactive mode, --method selects an allowed persisted-secret mode (default api_key), and --backend is token metadata, not backend provisioning or full tuple validation. Scripted login saves a token under global:default_<provider> but does not create backend/auth/binding config or materialize global config. Using that token requires an already-configured matching managed_store binding; see the scripted API-key example. Alternatively, use environment-key auth. If --secret is omitted, scripted login reads one line from stdin. copilot is the exception. rkat auth login copilot --non-interactive checks a GitHub token (from --secret or one line of stdin), stores it under the shared github_copilot credential account, and writes the three Copilot routes global:copilot_openai, global:copilot_anthropic and global:copilot_gemini with auth_method = "github_copilot_token". With --from-env it stores nothing and writes routes that read COPILOT_GITHUB_TOKEN, then GH_TOKEN, then GITHUB_TOKEN, checking the token when one is set. A token that fails the check is never stored, and --backend and --method are refused. Both rkat auth login copilot forms refuse, before writing anything, a [realm.global] that configures its Copilot account once in a [copilot] section (see GitHub Copilot configured once). Runtime credential reads inherit down the realm chain. CLI auth administration differs: --realm on profile, status, test, and refresh commands selects an owner section within the scope’s already-loaded effective config (normally the workspace/global chain). It does not by itself discover <state-root>/<selected-realm>/config.toml or inherit a missing profile/binding for those subcommands. The selected owner’s sections must already be reachable, for example through a workspace parent link at the same state root or a multi-section workspace/global document. The default owner section is global. HostAuthService and RPC/REST credential writes are strict-owner and reject child-addressed inherited writes. Current CLI logout exception: when the loaded config resolves child:<binding> to an inherited owner, rkat auth logout child:<binding> can clear that owner’s stored credential, including a shared credential account used by other routes. Explicitly address the true owner instead. A bare logout binding means global; --realm does not retarget logout. Config get / set / patch still operate on the raw head document. See Realm inheritance and the auth guide for the full model.

models

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

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.

storage

Storage administration verbs. All of them dispatch before realm resolution, so they run against the exact on-disk state they diagnose — including split-brain realms the normal resolver refuses. Because no runtime scope is resolved, the global --isolated and --default-model flags are rejected as usage errors on every storage verb rather than silently ignored; scope the sweep with --realm, --root, or --state-root instead.
Read-only and safe against a live realm: takes no leases, never changes logical database content, and never creates a database or directory. SQLite may create or update the -wal/-shm sidecars needed for a coherent WAL read. Sweeps the invocation-context-local (<context-root>/.rkat/realms) and user-global roots by default. Ordinary runtime resolution first walks to the nearest ancestor containing .rkat, so run the storage verb from that project root (or pass --root) to inspect the same local candidate; any explicit root (--state-root or repeatable --root) restricts the sweep to exactly those roots. --realm focuses the sweep on one realm. Reports per-root realm inventory, schema-ledger state per database, dual-root twins, dangling session→blob references, orphaned lease/lock/backup artifacts, and the SQLite lock profile the rkat binary runs with (a sqlite-lock-profile warning when a process-wide lock is on). It also lists, as informational findings, the sessions written at session envelope 5 (operator-instruction-envelope) and the mob databases that hold operator-instruction events (operator-instruction-mob-events), which a release before 0.9.9 refuses, and the identity-store rows of schema version 2 or later of each mob database that holds any (identity-store-rows, counts only), which a release before 0.9.9 does not read (see Downgrading to 0.9.8), and the mob databases whose journal holds more than 64 operator instruction records or more than 1 MiB of Active bodies in total (operator-instruction-mob-totals), which a release before 0.9.15 cannot serve (see Rolling back to 0.9.14). Exit 0 means no error-severity findings; exit 1 means errors were found.
migrate is dry-run by default, offline, resumable, and fail-closed. It sweeps the same roots (and honors the same --realm filter) as storage doctor. The dry run reads each realm’s schema-ledger baseline read-only — no fence, no store opens, no mutation. --apply acquires the realm’s exclusive maintenance fence (--fence-wait-secs, default 10, bounds the wait for in-flight store operations to drain and kept connections to close), then per realm: stamps ledgers by opening every store through its normal constructor under the held fence and reports state-root adoption (report-only — realms are used where they lie). Exact 0.8.10 session-state conversion is owned by each backend’s activation transaction, which binds the released schema, key, and source bytes before installing current store authority; storage migrate does not bulk-adopt documents or defer conversion to ordinary reads. A realm materialized under multiple swept roots is a fail-closed refusal unless --apply --adopt-root <path> names the swept root whose copy to keep: every copy is fenced first, the divergence report is recomputed under the held fences, and archiving is gated on that comparison being conclusive (an unreadable entry poisons it and refuses) — then every other copy is archived read-only under the registered *.pre-<version>-<timestamp> backup naming. Divergent data is preserved and reported, never merged. Before its maintenance fence, the resolution takes each copy’s realm admission fence without waiting and holds it through the archive: while an admission holds any copy, the resolution is refused, naming the fence. Per-mob databases under mobs/ are report-only, and credential stores are never read, moved, or reported. Exit 0 = clean; exit 1 = errors or fail-closed refusals (split-brain without --adopt-root, unacquirable maintenance fence, a held or unusable admission fence). --bridge-pre-0-8-10 is an explicit --apply-only maintenance lane for SQLite realms. JSONL and memory realms are rejected before any database is mutated. While the realm fence is held, it runs a frozen importer before the normal store constructors. A domain is authenticated as exactly one caller-authorized source catalog; an unknown or ambiguous catalog refuses that domain instead of being inferred or stamped, and each domain owns its own transaction, so a domain that committed stays committed when a later one refuses. The same authentication answers the eligibility sentence an ordinary open prints, so a realm the bridge recovers is never described as unrecoverable and a realm it cannot recover is never handed this command. Row admission is per record, not per domain. Every runtime input row is carried forward when it decodes through the current typed contract and re-encodes without losing a field; a row that cannot be is left with its bytes exactly as found - never deleted, never blanked - and named in the output with the reason and the consequence. Rows are preserved in the current representation without being scheduled or replayed, and that includes their ingress payloads: a rescued realm keeps the operator’s own prompt whatever lifecycle state its input reached. A later session activation follows normal recovery, which applies this binary’s ordinary payload retirement to rows it writes itself. Ordinary store opens never enter this bridge.
prune owns the lifecycle of registered maintenance artifacts only — *.pre-<version>-<timestamp> migration backups and *.corrupt-<timestamp> index quarantines; nothing outside those naming patterns is ever touched. The default run lists artifacts with sizes and ages; --apply deletes those at least --older-than-days (default 30; 0 = all) days old. Age comes from the timestamp embedded in the registered name, not filesystem mtime — renames preserve mtime, so a long-idle file archived today would otherwise look instantly prunable. --realm restricts eligibility to one realm’s artifacts. Exit 0 = clean; exit 1 = deletion failures. Not to be confused with rkat realm prune, which deletes whole realm directories.
hosts-fences reports whether each directory’s filesystem can host a realm admission fence. It runs, in this process’s own view of the filesystem, the one predicate that fence writers, holders and verifiers use, and prints one JSON object per directory, one per line, in argument order, and nothing else on stdout: {"dir": "<path>", "hosts": true} (or false), or, when the directory’s filesystem could not be inspected (a directory that does not exist, for one), {"dir": "<path>", "unavailable": {"kind": "<kind>", "cause": "<text>"}}, where kind is a stable snake_case name and cause is for people. It runs before any realm, state, config or auth step, creates nothing, and takes no global option (giving one is a usage error). Exit 0 when every directory was evaluated, whatever the answers; exit 1 only when the report could not be written; exit 2 on a usage error, or when the process could not start at all (for example, a refused thread spawn), as for every command. See Realm admission fences.

mcp

rkat mcp manages the selected realm’s own MCP servers (--scope realm) and the project and user mcp.toml files.
--scope realm writes [[tools.mcp_servers]] in the realm’s own config (the realm selected by --realm), which its child realms inherit. Only that list changes; the rest of the config document is kept as written. --expected-generation refuses the write unless the realm config is still at that generation (rkat config get --with-generation). A server that a realm only inherits is removed in the realm that configures it. Realm servers are literal: --scope realm refuses a ${VAR} reference in the command, args, -e values, URL or -H values; put env-derived values in mcp.toml. --allow-operation <OPERATION> (repeatable) allows only the named raw MCP operations on the server; every other operation is refused and not offered. --oauth-account sets the OAuth account a streamable HTTP server’s login must prove (the provider subject ID, not an email or display name). --oauth-account-selection discover binds the account the provider verifies at the first login instead, and --oauth-account-selection unverified is an explicit opt-in to resource-bound access with no account evidence; the two flags conflict. add prints the selection it wrote, and for a streamable HTTP server without either flag (and without a static Authorization header) it names these choices in case the server uses OAuth sign-in. Examples:
Omit --scope on list or get to search all configured scopes, the realm included. HTTP OAuth is discovered when connecting, not stored in .rkat/mcp.toml. Interactive login requires an account selection on the server entry: its oauth_account (the account the login must prove; the OpenID Connect sub for the default strategy), or oauth_account_selection = "discover" (bind the account verified at the first login) or "unverified" (an explicit opt-in for servers that cannot prove an account; no account is verified). rkat mcp add writes them (--oauth-account, --oauth-account-selection); rkat mcp get shows them. rkat mcp login never sets or changes a selection. Without one it refuses before any network request and prints the rkat mcp remove and rkat mcp add commands for each choice. discover and --oauth-account need account evidence: the default strategy reads the issuer’s OpenID Connect UserInfo endpoint, and an issuer without one is refused before client registration, with no credential stored and the selection unchanged; the refusal says to retry first if the issuer could not be reached, and names unverified as the deliberate alternative. A slot that holds a credential this login may not replace is refused with the way to disconnect it (RPC auth/logout with the MCP target, or the SDK helpers; rkat has no disconnect command). The printed commands single-quote the server name and URL, so they paste as shown. A login, including one during rkat run --mcp-auth interactive, reports the account it bound, or that the credential is unverified. Use rkat mcp login <NAME> to open the browser flow ahead of time (--allow-headless permits it without an interactive terminal and prints the authorize URL to stderr if no browser opens, so avoid it where output is captured or logged), or rkat run "..." --mcp-auth interactive to allow a TTY run to authenticate when an HTTP MCP server with an account selection first requires it. The CLI owns the loopback callback and your browser; agents never see the authorize URL or callback data. The default --mcp-auth stored uses persisted tokens only, and a server without a usable credential is reported as awaiting human authorization.

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.
Multi-host notes:
  • rkat mob host starts only the signed member-host and optional live listeners. It uses the workspace-derived realm (or explicit --realm) and rejects --isolated; it does not expose an RPC, REST, or MCP console.
  • When enabling the host pairing branch, prefer --pairing-password-env or --pairing-password-file so the secret does not appear in process arguments. The three pairing-secret options are mutually exclusive; --pairing-password remains available for compatibility. Pairing secrets must be at least 32 bytes and are validated before host startup effects. Pairing is accepted only on an IP loopback listener because it returns the one-time binding descriptor over the plaintext comms transport. Use the 0600 descriptor out-of-band for remote hosts, or tunnel a loopback listener.
  • rkat mob bind-host consumes the descriptor JSON written by rkat mob host --descriptor-out; the 0600 descriptor carries a single-use bootstrap token, and the bind report (host id, authority epoch, capability record) prints as JSON.
  • grant, revoke-grant, and grants manage the closed control-scope set: list, read_history, subscribe_events, send_command, cancel, retire, wire_topology, live, admin_host, and admin_grants.
  • rkat mob live open prints the wire LiveOpenResult JSON — including the live URL and single-use token — to stdout only; stderr carries a token-free note. The socket it names is the input plane: there is no live send verb.
  • --transport is the member’s own live host’s to serve or refuse. A member host started by rkat mob host serves WebSocket only, so it refuses --transport webrtc (LiveTransportUnsupported), and the one-shot CLI composes no live host for a member it runs itself. WebRTC to a member goes through JSON-RPC mob/member_live_open with transport: "webrtc" and live/webrtc/answer on the same server. Session-scoped live/open refuses a mob member’s session, and controller session/* methods do not proxy a placed member’s host-local session in multi-host v1.
  • Mob verbs exit with typed codes: scope denied 45, host unavailable 46, stale cursor 47, stale fence 48, and stale delivery scope 56 (the member’s session rotated under a still-current fence; capture the delivery scope again), each with a one-line detail: {...} JSON rendering on stderr. Everything else keeps the generic exit 1.
  • Durable member role migration is not a CLI spawn option. The one-shot resume_from_role declaration is restricted to trusted in-process SpawnMemberSpec construction and the private member-host materialization protocol. CLI helpers, public RPC/SDK spawn requests, REST, MCP, and standing profiles cannot grant it.
Examples:

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). mob web build copies those artifacts into its output. wasm-pack is one way to generate the required input:
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). The generated page trust-verifies the package and initializes the WASM runtime only. It does not call mob_create, spawn members, or provide a transcript UI; integrate the package with the generated WASM glue or @rkat/web to build those application flows.

skill

workgraph

rkat workgraph provides operator lookup plus narrow goal and attention controls for the active realm.
The CLI’s WorkGraph grant covers one namespace, default, in the selected realm: other --namespace values and --all-namespaces are refused. 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.

capabilities

Shows status for compiled/runtime capabilities.

init

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