revka agent

revka agent starts the agent loop from your terminal. With no arguments it opens an interactive chat session against your configured provider and model; with -m it runs a single query, prints the answer, and exits. Either way the agent has access to its full tool set, memory, and skills.

Use this command to talk to your agent locally, script one-off queries in a pipeline, or test a provider/model/temperature combination without editing config.toml. For a running, always-on agent that also serves the dashboard and channels, see revka gateway, daemon & service.

For background on what happens inside a turn, see The agent loop. For how conversation state is kept, see Sessions & conversation state.

Synopsis

revka agent [-m <TEXT>] [--session-state-file <PATH>] \
            [-p <ID>] [--model <MODEL_ID>] [-t <TEMP>] \
            [--peripheral <board:path>]...

revka agent                                                   # interactive session
revka agent -m "Summarize today's logs"                       # single message
revka agent --provider anthropic --model claude-sonnet-4-20250514
revka agent -p openrouter --model openai/gpt-4o --temperature 0.3
revka agent --session-state-file session.json                 # load/save state

Flags

Flag	Short	Value	Meaning
--message	-m	<TEXT>	Single-message mode: run one query, print the response, and exit instead of entering the interactive loop.
--session-state-file		<PATH>	JSON file used to persist and restore interactive session state across runs.
--provider	-p	<ID>	Override the configured default provider for this run (e.g. anthropic, openrouter, openai, openai-codex).
--model		<MODEL_ID>	Override the configured default model for this run.
--temperature	-t	0.0–2.0	Override the configured sampling temperature for this run.
--peripheral		<board:path>	Accepted and logged, but not yet wired into the agent — does not attach a device for the session. Repeatable.

Note

--model and --peripheral have no short form. The short flags are -m (message), -p (provider), and -t (temperature).

Interactive vs single-shot

Interactive session

Running revka agent with no -m opens a persistent chat loop. The agent keeps conversation history across turns within the session, so follow-up questions retain context.

revka agent

Inside the loop, type natural-language messages, or use these built-in commands:

Command	Action
/help	Show the available in-chat commands.
/clear or /new	Clear the conversation history. Prompts for confirmation, then deletes conversation and daily memory; long-term core memories are preserved.
/quit or /exit	Leave interactive mode.
/think:<level>	Set reasoning depth for the next turn. Levels: off, minimal, low, medium, high, max.

The interactive prompt also understands natural-language routing instructions, for example: “conversation uses kimi, coding uses gpt-5.3-codex”.

Caution

Config hot-reload is not supported in agent mode. If you change config.toml while an interactive session is open, restart revka agent for the new settings to take effect. (Hot-reload does apply to the long-running daemon and channels.)

Single-shot query

Pass -m/--message to run exactly one query. The agent prints its final response to stdout and exits, which makes it convenient for scripts, cron jobs, and CI:

revka agent -m "Summarize today's logs"

Because output goes to stdout, you can capture or pipe it:

SUMMARY="$(revka agent -m 'One-line status of the build')"

Single-shot mode does not read or write the interactive session-state file; it runs a one-off turn.

Provider, model & temperature overrides

The three override flags let you try a different backend for a single run without touching config.toml. Each overrides only the corresponding configured default for that invocation:

# Use Anthropic + a specific model for this run only
revka agent --provider anthropic --model claude-sonnet-4-20250514

# Route through OpenRouter to a model id, with a lower temperature
revka agent -p openrouter --model openai/gpt-4o --temperature 0.3

• -p/--provider overrides default_provider.
• --model overrides default_model.
• -t/--temperature overrides default_temperature.

When a flag is omitted, the value from config.toml is used.

Caution

--temperature must parse as a float within the inclusive range 0.0 to 2.0. A value outside that range (or a non-numeric value) is rejected before the session starts, with an error such as temperature 3 is out of range (expected 0..=2).

The same overrides are also available as environment variables, which is handy in containers and CI. These shadow the matching config.toml keys for the whole process:

REVKA_PROVIDER=anthropic \
REVKA_MODEL=claude-sonnet-4-20250514 \
REVKA_TEMPERATURE=0.3 \
revka agent -m "hello"

Variable	Overrides
REVKA_PROVIDER	default_provider
REVKA_MODEL / MODEL	default_model
REVKA_TEMPERATURE	default_temperature
REVKA_API_KEY / API_KEY	api_key

For the full provider catalog and how to register custom or local endpoints, see Custom providers & local LLMs and revka models, providers & auth.

Session state files (--session-state-file)

--session-state-file <PATH> points the interactive loop at a JSON file used to persist and restore the conversation:

revka agent --session-state-file session.json

• On start, if the file exists, the prior conversation history is loaded so you resume where you left off. If it does not exist, the session starts fresh.
• After each turn, the updated history is written back to the file.
• On /new or /clear, the cleared state is saved to the file as well.

The path is also used to derive a stable session identifier, so memory tied to that session lines up with the saved history. Point different files at different ongoing conversations to keep them separate.

# Resume an ops conversation, separate from a research one
revka agent --session-state-file ~/.revka/sessions/ops.json
revka agent --session-state-file ~/.revka/sessions/research.json

Note

The session-state file is an interactive-mode feature. It is read and written only when you run an interactive session, not in single-shot (-m) mode.

See Sessions & conversation state for the broader model of how Revka tracks conversations.

--peripheral flag (not yet wired)

--peripheral <board:path> is accepted by the CLI and its value is logged, but it is not currently wired into the agent — passing it does not attach a device or expose any hardware tool calls for the session. The agent’s peripheral tools are built exclusively from the [peripherals] section of config.toml.

To make peripherals available to the agent, register them persistently via revka peripheral add or by editing config.toml directly. For the full board list, flashing, and persistent registration, see revka hardware & peripheral.

Examples

# Interactive session on your configured defaults
revka agent

# One-off summary, captured into a variable
NOTES="$(revka agent -m 'Summarize the last hour of audit events')"

# Try a different provider/model/temperature for one run
revka agent -p anthropic --model claude-sonnet-4-20250514 -t 0.2

# Resume a named, persisted conversation
revka agent --session-state-file ~/.revka/sessions/daily.json

Related pages

• The agent loop — what happens inside each turn.
• Sessions & conversation state — how conversations are tracked and resumed.
• Chat with your agent — end-to-end guide to talking to your agent.
• Custom providers & local LLMs — provider/model setup for the override flags.
• revka models, providers & auth — manage the model catalog and provider auth.
• revka gateway, daemon & service — run the always-on agent with dashboard and channels.
• revka hardware & peripheral — register, flash, and configure peripherals.
• CLI overview & environment — global flags and environment variables.