CLI configuration

​

Global runtime scope flags

All CLI commands accept realm scope flags:

• --realm <id>
• --instance <id>
• --realm-backend <sqlite|redb|jsonl> (creation hint only)

These flags decide which realm config/session state is used.

​

Default realm behavior

If you want CLI + RPC to share the same state, pass the same explicit --realm to both.

​

Environment variables

Required API keys (at least one): See providers for full key precedence (RKAT_* variants included).

​

Config files

Canonical runtime config for CLI commands is realm-scoped (<realm>/config.toml under platform data dir). Compatibility files still exist: These are useful for templates (rkat init) and compatibility workflows, but realm config is the runtime source of truth for CLI/RPC/REST/MCP surfaces.

​

Session storage layout

Realm storage lives under platform data dir:

• macOS: ~/Library/Application Support/meerkat/realms/<realm>/
• Linux: ~/.local/share/meerkat/realms/<realm>/
• Windows: %APPDATA%\meerkat\realms\<realm>\

Important files:

• realm_manifest.json (backend pinning)
• config.toml (realm config)
• sessions.sqlite3 (when backend is sqlite)
• sessions.redb (when backend is redb)
• sessions_jsonl/ (when backend is jsonl)
• mob_registry.json (CLI mob registry)
• mob_registry.lock (CLI mob registry lock)

--realm-backend is a creation hint. After first realm creation, backend selection is pinned by realm_manifest.json. This applies to both session storage and rkat mob command behavior in that realm. When SQLite support is compiled in, new persistent realms default to sqlite.

​

MCP configuration

MCP servers are configured separately from realm runtime state: Project servers override user servers with the same name.

​

Exit codes

​

See also

• Realms
• CLI commands
• Configuration