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 |
--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 |
--queue | Start the session already working the project task queue, the way /queue starts that drive by hand: one open, due task at a time in the queue's own order, each finished in the queue before the next is picked, and the drive stops by itself once nothing is left that an agent may work — saying whether the queue is empty, whether every task left is held by a wait, after, until or on, or whether every task left is marked needs user. It does not run beside a goal run: the two never drive one session at the same time. It configures the session, so revolve detach and revolve wake hand it on, while a peer an agent starts does not inherit it. See Working unattended |
--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 |
--license | Print the program's own license and the third-party notices of the bundled dependencies, 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.
Subcommands
A subcommand is the first word on the line and takes the place of the options above.
This directory's sessions
| Command | Effect |
|---|---|
revolve sessions | List this directory's sessions on stdout, newest first. The same as --list, which still works |
revolve resume | Open the newest session of this directory. The same as --resume |
revolve import [name] | List what Claude Code and OpenCode left in this directory, or carry one conversation over. The same as --import |
These three were options before they were words, and the options are kept: a word reads better on the line and sits where every other subcommand sits, while a script that already types -l or -r keeps working.
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>] [in <dir>] <text> | Write a task into the project queue, or with in into another project's, 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 projects [busy|stale|new] [<window>] [<count>] | The same view across every project on the machine rather than inside one: a line per task folder naming how many tasks are open, how many are held by a wait, a dependency or a command, how many are marked for the user, and how long since one was touched. busy puts the fullest queue first, stale the project nobody has touched in longest, and new the one whose queue moved most inside the window — a span such as 12h, 7d or 2w, one day by default. The count caps how many projects are named, twenty by default |
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 |
revolve migrate [<directory>] | Sweep a directory of repositories, moving each one's legacy .tasks/ into its project task queue, the same motion a session does on its first start since the migration — so a repository nobody has opened stops hiding its tasks from revolve projects and revolve tasks. Without an argument it sweeps the working directory's parent; a repository is any directory holding a .git. It names per repository what it moved, and a name the queue already holds stays where it is |
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.