CLI overview & environment

Revka ships as a single Rust binary, revka, that covers the entire lifecycle of a memory-native AI agent: first-run setup, interactive and single-shot agent sessions, the HTTP/WebSocket gateway and its embedded dashboard, channel integrations, scheduling, OS service management, emergency-stop safety, memory inspection, model catalog management, hardware control, and diagnostics. This page is the map of that surface — the command groups, the one global flag, how Revka finds your config directory, how to export the config schema, and the complete environment-variable reference.

Every command runs offline. A running daemon is required only for operations that talk to the gateway (for example revka pair token or revka status --format exit-code); everything else works without one. Because environment variables shadow the equivalent config.toml keys, Revka is fully scriptable in CI/CD and container deployments.

If you are starting from scratch, install the binary first (Installation), then run revka onboard and follow the Quickstart.

Command shape

Every invocation follows the same shape — an optional global flag, a command, an optional subcommand, then flags:

revka [--config-dir <PATH>] <command> [subcommand] [flags]

revka onboard --api-key "sk-..." --provider openrouter
revka --config-dir /srv/revka daemon -p 8080
revka doctor traces --event tool_call --contains "shell"

Run revka --help, or revka <command> --help, for the authoritative flag list of any command on your installed version.

Command groups

The commands fall into a handful of functional groups. Each links to its dedicated reference page.

revka agent Interactive chat and single-shot queries, session state, provider/model/temperature overrides, peripheral attachment.

revka gateway, daemon & service Run the gateway, the full daemon, or register Revka as an OS service. Pairing codes.

revka cron Schedule recurring, one-shot, interval, and delayed agent or shell jobs.

revka channel & integrations Add, remove, list, health-check, bind, and send through messaging channels.

revka models, providers & auth Inspect provider catalogs, list providers, and manage subscription auth profiles.

revka memory & estop Inspect local memory entries and engage or resume emergency-stop states.

revka skills, workflows & sop Install, audit, and test skills; sync built-in Operator workflow templates.

revka doctor, status & self-test Diagnostics, system summary, model-catalog probes, trace queries, and self-tests.

revka hardware & peripheral Discover USB devices and register, flash, and configure hardware peripherals.

revka install, update, migrate, completions & ACP Sidecar install, binary updates, runtime migration, shell completions, and the ACP server.

This page covers the three things that span all of those groups: the --config-dir flag, the revka config schema export, and the environment-variable layer. First-run setup (revka onboard) is its own page — its flag reference is summarized below and covered fully in the Onboarding wizard.

Offline-first design

Most subcommands operate purely on your local config and workspace and never reach the network unless the work itself requires it:

• No daemon required — onboard, agent, config schema, cron CRUD, memory, estop, skills, workflows, completions, doctor, and the hardware/peripheral commands all run standalone.
• Daemon required — operations that call the gateway, such as revka pair token (exchanges a pairing code over HTTP) and revka status --format exit-code (does a GET /health against the configured gateway).
• Completions are side-effect free. revka completions <shell> writes only to stdout — it loads no config and emits no logs — so the output is safe to source directly from a shell init script.
• Offline CI validation. revka self-test --quick skips the network checks (gateway health, memory round-trip), making it suitable for air-gapped or CI environments. It exits non-zero if any test fails.

Global flag: --config-dir

--config-dir overrides the configuration directory for all commands. It is the only true global flag, and it must come before the subcommand:

revka --config-dir /custom/path daemon

• Setting --config-dir also sets the REVKA_CONFIG_DIR environment variable for the process, so any child process Revka spawns sees the same directory.
• An empty string is rejected with an error.
• It is equivalent to exporting REVKA_CONFIG_DIR before the call.

Config directory resolution

When you do not pass --config-dir, Revka resolves which config.toml to load through a three-level precedence chain:

1. REVKA_WORKSPACE — if set, this workspace directory wins absolutely; the config directory is derived from it.
2. ~/.revka/active_workspace.toml — a persisted marker file written by revka onboard that points at the selected workspace. This is why your workspace path persists between runs.
3. Default — ~/.revka/config.toml.

REVKA_CONFIG_DIR (or the --config-dir flag it backs) overrides the entire config directory and is applied before the config file is loaded.

Caution

Homebrew installs default to /opt/homebrew/var/revka/, which differs from the ~/.revka/ directory a manual install uses. revka onboard warns when the config it writes diverges from the path your service runs against — copy or link your workspace before running Revka as a service. See the macOS lifecycle page.

For the full set of config.toml sections and keys, see the Configuration overview.

revka onboard flag reference

revka onboard is the first command you run. It auto-detects whether to run the interactive wizard or the non-interactive quick setup based on your terminal and the flags you pass. The full walkthrough lives in the Onboarding wizard page; the flags are:

Flag	Meaning
--force	Overwrite an existing config without confirmation (and run the full wizard instead of provider-only update mode).
--reinit	Back up the entire config directory with a timestamp suffix, then onboard from scratch. Cannot combine with --channels-only.
--channels-only	Run the fast channel-repair wizard only. Cannot combine with --api-key, --provider, --model, --memory, --force, or --quick.
--api-key <KEY>	Provider API key. Triggers quick (scriptable) setup.
--provider <ID>	Provider name, e.g. openrouter, anthropic, openai. Triggers quick setup.
--model <MODEL_ID>	Model override. Triggers quick setup.
--memory <kumiho|none>	Memory backend selection for quick setup.
--quick	Skip interactive prompts and use quick setup with defaults.
--lang <en|ko>	Wizard UI language. Overrides REVKA_LANG and $LANG.

revka onboard                                         # interactive wizard in a TTY
revka onboard --quick                                 # force quick setup
revka onboard --api-key "sk-..." --provider openrouter
revka onboard --channels-only                         # repair channels only
revka onboard --reinit                                # back up old config, start fresh

REVKA_INTERACTIVE=1 forces the interactive wizard even without a TTY, and REVKA_AUTOSTART_CHANNELS=1 auto-launches channels on completion.

revka config schema — JSON Schema export

revka config schema dumps the machine-readable JSON Schema (draft 2020-12) for the entire config.toml contract to stdout. The schema documents every available key, its type, default, and description, making it the source of truth for the config format.

revka config schema                 # print to stdout
revka config schema > schema.json   # save for tooling

The most common use is editor validation. Point your editor’s JSON-Schema support at the exported file to get autocompletion and inline validation while you edit config.toml. In VS Code, for example:

.vscode/settings.json

{
  "evenBetterToml.schema.associations": {
    ".*/config\\.toml$": "./schema.json"
  }
}

This is a read-only, offline command — it needs no daemon and the emitted schema is independent of your config values.

Environment variables

Environment variables shadow the equivalent config.toml fields without modifying the file, which makes them the natural way to configure Revka in CI/CD and containers. They are applied after the config file is loaded, in an apply_env_overrides pass.

.env loading semantics

Before the env-override pass runs, Revka auto-loads the .env file from your active workspace (<workspace>/.env):

1. The config file is loaded (config.toml resolved as described above).
2. The workspace .env file, if present, is parsed line by line. Blank lines and # comments are skipped; each KEY=VALUE is set into the process environment — only if that key is not already set. Keys already present in the environment therefore take precedence over .env values.
3. KUMIHO_SERVICE_TOKEN gets a final fallback: if it is still unset after .env loading, Revka reads it from the Kumiho CLI’s auth file at ~/.kumiho/kumiho_authentication.json (the control_plane_token field). Normal onboarding writes the token to the workspace .env, which takes precedence over this fallback.
4. apply_env_overrides runs, layering the resulting environment over the loaded config.

Note

The precedence to remember is: explicit shell environment > workspace .env > config.toml. REVKA_CONFIG_DIR is special — it is read before the config file is loaded, since it determines which config to load in the first place.

Provider key precedence

A provider API key is resolved from several sources. The order is:

1. An explicit api_key in config.toml.
2. A provider-specific environment variable, e.g. OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY, XAI_API_KEY, MOONSHOT_API_KEY, GLM_API_KEY, ZAI_API_KEY, and the other *_API_KEY variables Revka recognizes.
3. The generic REVKA_API_KEY (or legacy API_KEY).

For the provider env var per backend, and for OAuth/subscription providers, see revka models, providers & auth and the Provider catalog.

Note

The legacy provider variable PROVIDER only overrides the config default when the config still reads openrouter (the default). REVKA_PROVIDER always wins when set.

Core reference

Variable	Overrides	Notes
REVKA_CONFIG_DIR	--config-dir flag	Config + workspace directory. Read before config load.
REVKA_WORKSPACE	workspace_dir	Active workspace directory (config dir is derived from it).
REVKA_API_KEY / API_KEY	api_key	Generic provider API key.
REVKA_PROVIDER / PROVIDER (legacy)	default_provider	Provider ID. PROVIDER only wins if config still reads openrouter.
REVKA_MODEL / MODEL	default_model	Model ID.
REVKA_MODEL_PROVIDER / MODEL_PROVIDER	default_provider	Codex app-server style alias.
REVKA_TEMPERATURE	default_temperature	Float 0.0–2.0.
REVKA_GATEWAY_PORT / PORT	gateway.port	Gateway listen port.
REVKA_GATEWAY_HOST / HOST	gateway.host	Gateway bind host.
REVKA_REQUIRE_PAIRING	gateway.require_pairing	Boolean.
REVKA_ALLOW_PUBLIC_BIND	gateway.allow_public_bind	Boolean.
REVKA_WEB_ROOT	gateway.web_root	Filesystem path for dashboard assets.
REVKA_LANG	language	Wizard/UI language (en, ko).
REVKA_LOCALE	locale	Tool-description locale (wider set, e.g. zh-CN, ja-JP).
REVKA_EXTRA_HEADERS	extra_headers	Format Name:Value,Name2:Value2.
REVKA_PROVIDER_TIMEOUT_SECS	provider HTTP timeout	Integer seconds.
RUST_LOG	tracing log filter	e.g. debug, info, revka=trace.

Onboarding behaviour

Variable	Effect
REVKA_INTERACTIVE	1 forces the interactive onboard wizard even without a TTY.
REVKA_AUTOSTART_CHANNELS	1 starts channels immediately after onboarding completes.

Skills

Variable	Overrides	Notes
REVKA_OPEN_SKILLS_ENABLED	skills.open_skills_enabled	1/0/true/false/yes/no/on/off.
REVKA_OPEN_SKILLS_DIR	skills.open_skills_dir	Skill directory path.
REVKA_SKILLS_ALLOW_SCRIPTS	skills.allow_scripts	Opt in to script files in skills.
REVKA_SKILLS_PROMPT_MODE	skills.prompt_injection_mode	full or compact.

Reasoning & web search

Variable	Overrides	Notes
REVKA_REASONING_ENABLED / REASONING_ENABLED	reasoning.enabled	Extended-thinking toggle.
REVKA_REASONING_EFFORT / REVKA_CODEX_REASONING_EFFORT	reasoning effort	Provider-specific.
REVKA_WEB_SEARCH_ENABLED / WEB_SEARCH_ENABLED	web search enable	Boolean.
REVKA_WEB_SEARCH_PROVIDER / WEB_SEARCH_PROVIDER	web search provider	String.
REVKA_BRAVE_API_KEY / BRAVE_API_KEY	Brave Search API key	String.
REVKA_SEARXNG_INSTANCE_URL / SEARXNG_INSTANCE_URL	SearXNG instance	URL.
REVKA_WEB_SEARCH_MAX_RESULTS / WEB_SEARCH_MAX_RESULTS	max results	Integer.
REVKA_WEB_SEARCH_TIMEOUT_SECS / WEB_SEARCH_TIMEOUT_SECS	search timeout	Integer.

Storage & proxy

Variable	Overrides	Notes
REVKA_STORAGE_PROVIDER	storage.provider	String.
REVKA_STORAGE_DB_URL	storage.db_url	Connection URL.
REVKA_STORAGE_CONNECT_TIMEOUT_SECS	storage connect timeout	Integer.
REVKA_PROXY_ENABLED	proxy.enabled	Boolean.
REVKA_HTTP_PROXY / HTTP_PROXY	HTTP proxy URL	URL.
REVKA_HTTPS_PROXY / HTTPS_PROXY	HTTPS proxy URL	URL.
REVKA_ALL_PROXY / ALL_PROXY	all-traffic proxy (SOCKS5)	URL.
REVKA_NO_PROXY / NO_PROXY	proxy exclusions	Comma-separated.
REVKA_PROXY_SCOPE	proxy.scope	environment / revka / services.
REVKA_PROXY_SERVICES	proxy services	Comma-separated service keys.

Security & channel secrets

Variable	Overrides	Notes
REVKA_AUDIT_SIGNING_KEY	audit signing key	32-byte hex (64 chars).
REVKA_WHATSAPP_APP_SECRET	WhatsApp channel app secret	String.
REVKA_NEXTCLOUD_TALK_WEBHOOK_SECRET	Nextcloud Talk webhook secret	String.

Kumiho graph memory

Variable	Notes
KUMIHO_SERVICE_TOKEN	Kumiho auth token. Loaded from the workspace .env, or auto-injected from ~/.kumiho/kumiho_authentication.json if not already set.
KUMIHO_LOCAL_SERVER_ENDPOINT	Kumiho CE gRPC endpoint. Set automatically when CE (Community Edition) mode is active.
KUMIHO_UPSTASH_REDIS_URL	Redis URL for Kumiho CE. Set automatically when CE mode is active.

See Kumiho graph memory and Kumiho setup for the full memory configuration.

CE mode auto-injection (KUMIHO_*)

When [kumiho].mode = "local_ce" (self-hosted Community Edition), Revka points api_url at the CE default http://127.0.0.1:9190 and auto-injects the CE endpoint environment for the Kumiho MCP client, so you do not have to wire it up by hand:

• KUMIHO_LOCAL_SERVER_ENDPOINT — set to the CE server endpoint.
• KUMIHO_UPSTASH_REDIS_URL (or UPSTASH_REDIS_URL) — the Redis URL for CE, defaulting to redis://127.0.0.1:6379.

CE mode is tokenless, loopback-only, and single-user. The token precedence for the MCP client is KUMIHO_SERVICE_TOKEN over KUMIHO_AUTH_TOKEN — the service token (written by Revka onboarding) is read first, falling back to KUMIHO_AUTH_TOKEN. revka doctor probes the CE health endpoints (/api/_live, /api/_health) to confirm Neo4j, the event stream, and embeddings are reachable. See Kumiho setup for starting and validating a CE backend.

Examples

CI / scriptable

# Non-interactive bootstrap, config written under a custom directory
REVKA_CONFIG_DIR=/srv/revka \
REVKA_API_KEY="sk-..." \
REVKA_PROVIDER="openrouter" \
  revka onboard --quick

# Offline validation suitable for CI
revka self-test --quick

Container / daemon

REVKA_GATEWAY_HOST=0.0.0.0 \
REVKA_GATEWAY_PORT=8080 \
REVKA_ALLOW_PUBLIC_BIND=true \
  revka daemon

# Lightweight health probe (Docker HEALTHCHECK)
revka status --format exit-code

Debugging

RUST_LOG=revka=debug revka daemon
revka --config-dir /srv/revka doctor

Next steps

Onboarding wizard The full revka onboard walkthrough, modes, and config protection.

Configuration overview Every config.toml section, key, default, and env override.

revka doctor, status & self-test Diagnostics, system summary, and trace inspection.

revka gateway, daemon & service Run the runtime and register it as an OS service.