Command line
Every flag and every subcommand, and which of them start a conversation.
revolve [session-name] [options]The working directory of the process is the project that gets worked on, and sessions are keyed by it: a listing or a resume only ever considers conversations started in the same directory.
Options
| Option | Effect |
|---|---|
<session-name> | Resume the named session for this directory, or start a new one under that name |
--resume, -r | Resume the most recent session for this directory, named or not |
--list, -l | Print the named sessions for this directory and exit. The same sessions are reachable from a running chat with /resume, which switches the conversation without restarting the program |
--print <message>, -p | Run exactly one turn on this message and exit |
--json | With --print: one JSON object with the result on standard output, everything else on standard error. See Scripting |
--import [name], -i | List the conversations importable from another coding agent, or import that one under its own name and continue in it |
--worktree <branch>, -w | Put the sandbox into .worktrees/<branch>, creating the git worktree and the branch if they do not exist |
--role <name> | Run this session as the role written in subagents/<name>.md beside the memory directories. The document goes into the system prompt, so it holds for every turn and survives a compaction. An unknown name refuses to start. A leading key value header in that document names the files the role keeps in its prompt and the lane it belongs to; see a role that keeps files in front of it. revolve detach, revolve wake and the window hand it to the session they start, the way they hand on --config, --worktree, --lane, --model, --budget, --allow-all and --bare |
--lane <name> | Claim the task files whose names start with <name>- and state that rule in the system prompt |
--model <ref>, -m | Run this session on that model, named the way the /model command accepts it — anthropic:claude-sonnet-4-5, or a bare model id the catalog resolves. It configures the session rather than the frontend, so a detached session and the window are started with it too |
--budget <spec> | Cap one turn: rounds=<n>, output_tokens=<n>, seconds=<n>, comma-separated, 0 turning a limit off |
--allow-all, -A | Run commands no rule allows instead of denying them. deny rules still hold, and RequestPermission is still refused |
--auto | Never ask and never pause. A permission that would raise a prompt — an ask rule, or a call no rule covers — is granted, and this is where it differs from --allow-all: that flag leaves an ask rule asking, while this one answers it. A deny rule still refuses, and every other rule means what it meant. The system prompt says nobody is at the prompt, and the tools that would wait for a person — AskQuestions, RequestPermission, RequestFileGrant — are refused with a sentence pointing at AskInbox, so a genuine blocker becomes an inbox entry the user answers whenever instead of a turn that hangs. It configures the session, so revolve detach, revolve wake and the window hand it on |
--bare | Start from the compiled defaults: no memory, no skills, no prompt templates, no project context |
--cleanup delete|compact | How a one-shot worker session ends itself once it has reported: delete stops the session and frees its socket, compact keeps it addressable and condenses its history into working notes instead. It is what a session started by StartAgent with a worktree carries, and it does nothing in a session you are talking to yourself |
--rpc | Speak JSON lines on standard input and output instead of running a front end |
--acp | Speak the Agent Client Protocol version 1 on standard input and output, so an editor such as Zed or the VS Code ACP extension drives the session and draws the conversation |
--daemon | Run as a detached session in the foreground, listening on its socket |
--config <path>, -c | Use this config file instead of the default |
--version, -V | Print the version and exit |
--help, -h | Print the usage summary |
revolve-gui takes the same flags
The window is a second frontend on the same sessions, not a second program with its own vocabulary: revolve and revolve-gui parse their command line with the same code, so a session name, --resume, --config, --worktree, --lane, --role, --model, --budget, --allow-all and --bare mean there what they mean here, and every flag that configures a session is handed to the session the window starts.
What the window cannot be, it refuses by name. --print, --json, --rpc, --acp, --daemon, --import and --list write to standard output or are frontends of their own, and the subcommands print tables, so revolve-gui --rpc answers with a sentence naming the flag and the program to run it with rather than ignoring it.
--bare, and why it exists
Revolve can rewrite its own memory and write its own skills. A session that has accumulated bad instructions is therefore a session that behaves badly for reasons nothing on screen explains. --bare is the way back in: it starts from the compiled defaults and reads none of it, so you can talk to the agent about the instructions instead of moving files aside by hand.
--worktree, for two agents on one repository
Two agents writing in one working tree overwrite each other's uncommitted changes. --worktree feature-x puts the sandbox into a git worktree of its own, made on demand. A worktree shares the task queue, the memory and the permission rules of the repository it belongs to, because all three are keyed by the path of the main repository rather than by the working directory.
Subcommands
A subcommand is the first word on the line and takes the place of the options above.
Detached sessions
| Command | Effect |
|---|---|
revolve detach [name] | Start a session in the background and return to the shell |
revolve agents | List the sessions of this directory and every running session anywhere |
revolve attach <name> | Bring a terminal to a running detached session; --rpc watches it as JSON lines instead |
revolve stop <name> | Stop that session; revolve stop --all stops every running one |
revolve model <name> <model> | Point that running session at another model without stopping it: same socket, name and history, next turn on the new model |
Details under Scripting and embedding.
Signing in
| Command | Effect |
|---|---|
revolve login [provider] | Sign in with the browser OAuth flow, so calls bill against a subscription rather than an API key. Without an argument it signs in to anthropic, the one provider with a public flow to build against; a provider that has none explains which environment variable its API key belongs in instead of opening a browser tab against the wrong account. The chat command /login does the same from inside a session and defaults to the provider of the model you are running on |
Skill packages
| Command | Effect |
|---|---|
revolve install <git-url> [name] | Clone a skill package into the config directory |
revolve update [name] | Fetch the installed packages again, or only that one |
revolve remove <name> | Delete a package and the skills it brought |
revolve packages | List what is installed, from where, and at which commit |
revolve task [wait <when>] [as <name>] <text> | Write a task into the project queue, named from its own words or the name after as, and prefixed with the lane when --lane is given. A leading wait 3d or wait 2026-09-01 defers it. A name already taken gets a number rather than overwriting the file |
revolve tasks | List the open tasks, leaving out the deferred ones, urgent first |
revolve init | Create this project's memory/, tasks/ and subagents/ directories with their templates, and seed the global behavior rules if they are missing. It overwrites nothing and says what it wrote; the first session in a project does the same by itself |
Details under Skills and packages.
Waking a session on a schedule
| Command | Effect |
|---|---|
revolve wake <name> [message] | Give a turn to that session from outside, starting it detached if it is not running |
revolve schedule <when> <name> [message] | Put that wake into cron; <when> is HH:MM, a five-field cron expression, or a shorthand like @daily |
revolve schedule | List what is scheduled |
revolve schedule --remove <name> | Drop one schedule |
Details under Working unattended.
Which front end you get
| How you start it | What runs |
|---|---|
| On a terminal | The full-screen terminal interface |
| With piped standard input | Line mode: one turn per line in, plain text out |
-p <message> | One turn, the reply printed, exit |
-p <message> --json | One turn, one JSON object on standard output |
--rpc | JSON lines both ways, whatever standard input happens to be |
--acp | The Agent Client Protocol both ways: the editor draws the conversation |
--daemon | No front end at all: a socket other processes attach to |
Importing a conversation from another agent
A conversation held in another coding agent in the same directory can be carried over rather than retold.
revolve --import # what is importable: green for new, blue for already imported
revolve -i my-conversation # import that oneClaude Code conversations come from ~/.claude/projects/ and are named after their title. OpenCode conversations come from its SQLite database and are named after a slug of their title; that half needs a build with --features opencode, and a build without it simply lists none. An imported conversation keeps the name it had — Render stays Render — and where it came from is recorded in the session file's header rather than in front of its name, so the name you read in the other agent is the name you resume here. A session of this directory that already carries that name is not overwritten: the import refuses and names both, and the way on is to rename or remove the session standing there.
Importing a named conversation then continues straight into that session rather than exiting, so revolve -i my-conversation both imports and opens it. With --print, --json or --rpc the import stays what it was, a step that prints its report and ends.
What arrives is the conversation, not a replay: text is kept, a tool call becomes a → name line, and reasoning blocks and tool output are dropped. Afterwards it is an ordinary session — --resume finds it and /refine reads it.