rkat is designed for three main workflows:
- interactive terminal use
- scripts and CI
- Unix pipes and chained command composition
Global flags
All commands accept the same realm and convention-root flags:--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.
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:
--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
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
Tool presets
rkat uses presets instead of many enable/disable booleans.
--yolo is an alias for --tools full.
Provider and structured output controls
Use--param for common tuning and --params-json as the escape hatch:
--json is a convenience alias for --output json.
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.
Template defaults live under [presentation.html]:
--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
--streamis explicitly requested.
Stdin modes and Unix pipes
rkat treats piped stdin as a first-class interface:
autodefault: if stdin is piped, read it as one blob of contextblob: always read full stdin to EOF before runninglines: keep stdin open and process one line at a timeoff: ignore stdin even if something is piped in
--line-format json treats each incoming line as JSON instead of plain text.
run —resume
SESSION_ID accepts:
- a full UUID
- a short prefix
last~N
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:
session
config
--json (or --toml for set).
Examples:
auth
rkat auth login provisions the reserved global realm in the home-rooted
doc at ~/.rkat/config.toml — both the credential token and the
[realm.global] binding section. Because global is the universal tail of
every realm chain, a single sign-in is inherited by every workspace realm,
across workspaces, 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.
Credential reads inherit down the realm chain (a child realm resolves a
binding defined in a parent or in global), but credential writes are
strict-owner: a write targets the realm that defines the binding. --realm
on an auth command selects the realm and composes its chain for resolution,
without changing where an owned credential is persisted.
See Realm inheritance and the
auth guide for the full model.
models
self_hosted aliases and their server_id.
doctor
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.
<context-root>/.rkat/realms) and user-global candidate roots by default;
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, and orphaned
lease/lock/backup artifacts. 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), 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.
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).
--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. The importer accepts only authenticated, supported
pre-floor schema and row shapes; unknown, ambiguous, or inconsistent state
refuses instead of being inferred or stamped. The maintenance transaction preserves
queued and nonterminal runtime inputs in the current representation without
scheduling or replaying them. A later session activation follows normal
recovery. 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.
mcp
rkat mcp is for local and project configuration only.
--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 hoststarts 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-envor--pairing-password-fileso the secret does not appear in process arguments. The three pairing-secret options are mutually exclusive;--pairing-passwordremains 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-hostconsumes the descriptor JSON written byrkat 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, andgrantsmanage the closed control-scope set:list,read_history,subscribe_events,send_command,cancel,retire,wire_topology,live,admin_host, andadmin_grants.rkat mob live openprints the wireLiveOpenResultJSON — 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 nolive sendverb.- Mob verbs exit with typed codes for the four multi-host error classes:
scope denied
45, host unavailable46, stale cursor47, stale fence48, each with a one-linedetail: {...}JSON rendering on stderr. Everything else keeps the generic exit1.
Trust policy
--trust-policy strictrejects unsigned packs and unknown signers--trust-policy permissiveallows 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:
index.html (it includes the glue, a meerkat-bootstrap.js module, and the
mobpack).
skill
workgraph
rkat workgraph provides operator lookup plus narrow goal and attention controls for the active realm.
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
meerkat-models catalog (injected into meerkat-core as a ModelCatalog).
capabilities
doctor
- config readability
- common provider API keys
- MCP config loading
wasm-packavailability as one way to generate the required--wasmartifacts;mob web buildcopies them and does not invoke wasm-pack
init
.rkat/config.toml from the global template.