If you’d rather type than click, this page is for you. It lists every evolve command, grouped by what you’re trying to do. Skim the headings, find the job you’ve got, and copy the line.
Words this page uses
- Project: a codebase registered with Evolve, kept in a Git repository. A branch is a named line of work in it, like
main; a commit is a saved snapshot, named by a SHA (a long code like9f39c44c…); merging brings one line of work into another. - Goal (Evolve also says objective): what a run is for. Run: everything Evolve does for one goal. Attempt: one agent’s try at it. An agent is an AI tool that writes code.
- Policy: a project’s rules for judging changes, in its
evolve.yaml. Its checks are the tests Evolve runs on every attempt; protected files are the ones agents may never change. - Environment: a place Evolve puts changes live, like production. The known-good version is the one it goes back to in a rollback. A digest is the fingerprint of a built version.
- Supervised: an agent whose changes wait for your approval. A reviewer is an agent the operator (whoever runs Evolve) can set up to judge changes.
- Roadmap: a list of goals to build in order. Each goal’s scenarios (for a browser or installed app) or transcript (for a command-line program) say what it must do.
- Record: everything Evolve has written down, indexed in its database so it can answer quickly. A remote is the shared copy of your repository on a server like GitLab or GitHub. To fetch is to get changes from it; to push is to send yours.
- Planner: an agent the operator can set up to plan a run’s approaches before any attempt starts.
- Contract: a list of web requests and the answers a service must give. A milestone is a goal’s number on the roadmap: checks run everything up to it.
- To deploy is to put a version live; a promoted version is fully live.
- Signed: carrying a signature, a digital stamp that shows if a result was changed later.
- Web interface (or UI): Evolve’s web pages. Its Live view shows agents at work.
- Confidence review: Evolve’s report on how far it can trust each agent (Earned autonomy). Its numbers are called indicators.
- JSON: a plain-text format other programs can read;
--jsonprints that instead of a table. Exit status: the number a command finishes with; 0 means it went fine.
Reaching the server
The command talks to an Evolve server at EVOLVE_URL (http://127.0.0.1:7070 unless you set it) using the token in EVOLVE_TOKEN, a secret code that works like a password. After make up, source .evolve/env sets both for you.
evolve version prints which Evolve you have, then asks the server for its version and says if the two differ. Add --local to skip the server.
Many commands below take --repo R to name the project. Leave it out and Evolve uses the project your current directory is in.
Setting up
| Command | What it does |
|---|---|
evolve doctor |
checks everything Evolve needs and tells you how to fix what’s missing |
evolve init [dir] [N value]... [--plan] [--yes] [--name N] [--ref REF] |
reads the project and suggests a policy and its checks as numbered lines. Change any line by its number, then it writes, commits and registers them. A project that already has an evolve.yaml is registered as it is. A directory inside a bigger repository becomes the project’s root. --name sets the project’s name (the directory’s name if you don’t) and --ref the branch Evolve works on (the one you’re on if you don’t) |
evolve repo register [dir] [--name N] [--ref REF] |
registers a project that already has its evolve.yaml, as it is: no analysis, no questions. Useful if evolve init wrote the file but couldn’t reach the server |
evolve repo list |
registered projects, their branches and paths |
evolve repo rename OLD NEW |
renames a project (while none of its runs is going) |
evolve repo set NAME [--path DIR] [--ref REF] [--root DIR] |
points a project at a different checkout, branch or directory |
evolve repo remove NAME |
forgets a project that has no runs. One with runs stays, because the record is never rewritten; rename it out of the way |
evolve plan accuracy [--repo R] |
shows how the planner’s confidence compared with what actually happened over closed runs. Of the approaches it gave 75% or more, how many worked? It tells you whether its numbers mean anything, and where to set attempts.min_confidence |
evolve context [--repo R] |
the project’s shared context (verification/context.md): the things you’ve decided or explained, which every agent and reviewer reads |
evolve context add [--repo R] [--as NAME] "text" |
adds a dated entry to it and commits it to the project. Agents can never change it |
evolve skill [dir] [--global | --out DIR | --agents | --print] |
teaches an agent how to work Evolve. A skill is a set of instructions an AI coding tool loads when it’s relevant. This writes a Claude Code skill in the project (.claude/skills/evolve/), for every session on the machine (--global), in a shared skills library (--out DIR), or as a section of the project’s AGENTS.md, the instructions file that Codex and opencode (two other coding agents) read (--agents, rewritten in place). It’s generated from the Evolve you have installed, so it only names commands that exist. Run it again after upgrading |
evolve new <dir> [--does T] [--example E]... [--agent A] |
starts a project from nothing. Your examples become its contract, a bare-bones service and its policy are written and committed, and the first goal is to make every example pass |
evolve new <dir> --kind webapp [--does T] |
starts a browser app in Go, compiled to WebAssembly (so it runs inside the browser) and served by one program file, checked by browser scenarios |
evolve new <dir> --kind desktop [--does T] |
starts a native app (one you install) in Go with Gio, a toolkit for app interfaces in Go, checked by gui scenarios with no window |
evolve new <dir> --idea "…" [--kind K] [--yes] |
an agent suggests a roadmap of goals, each with the browser scenarios (web app), gui scenarios (native app) or example requests (service) that show it’s been reached. You review it, edit it and approve it. The kind, webapp, desktop or service, is picked from your idea unless you give it |
evolve roadmap [approve] [--repo R] [--yes] |
where the roadmap stands; approve approves a proposal you’ve edited. --yes skips the question |
evolve roadmap revise [--milestone N] [--repo R] [--yes] |
takes on your edits to verification/roadmap.yaml part-way through: goals reworded, added, or retired (retired: true keeps a goal’s number but drops its proof). The milestone stays where it is unless you move it. A reworded goal has to be reached again |
evolve driver update [--repo R] [--yes] |
brings a native app’s protected gui driver (the test program that works the app like a person) up to your Evolve’s, and commits it. It waits for a run that’s going unless you add --yes |
evolve policy check [--file evolve.yaml] |
checks a policy is valid and lists its checks |
evolve env bootstrap <env> --repo R [--wait] |
deploys the target branch as the first known-good version |
evolve env reconcile <env> |
for after a rollback Evolve couldn’t finish by itself and you finished by hand: confirms the platform is back on the known-good version and records it |
Goals and runs
| Command | What it does |
|---|---|
evolve objective create --file objective.yaml |
records a goal |
evolve objective list |
lists goals |
evolve run "a goal in a sentence" [--repo R] [--agent A] [--yes] |
turns your sentence into a goal the project’s checks can judge, shows it to you (along with any check it would tighten), then starts a run |
evolve run start --objective O --repo R [--agent A] [--wait] [--exit-status] [--idempotency-key K] [--yes] [--new-tests] [--read-tests] [--amend-tests] |
starts a run for a recorded goal. Send the same --idempotency-key twice (any text you pick) and you get the run the first one started, so a retrying script can’t start two |
evolve run reverify <run> [--attempt N] |
judges an attempt’s change again, with no agent involved: moved onto your branch as it is now, against the goal as it now reads. For code that was right and got rejected by a scenario that was wrong |
evolve run continue <run> [--attempt N] --note TEXT [--agent A] |
starts a run from an earlier attempt’s change, with its agent told what’s still left to do or fix. For a change that was mostly right, so nobody has to start from scratch. If the branch has moved on, the change is brought onto the current code |
evolve run answer <run> "text" |
answers the questions on a run that’s waiting for you. Your answer is added to the project’s shared context, and the reviewer decides again |
evolve run overrule <run> --reason TEXT [--attempt N] [--branch NAME] |
says a finished run picked wrong, whoever did the picking, and (with --attempt) which attempt was right. evolve run next then merges that one, or tries the goal again. The run’s record stays as it happened. If the wrong change is already merged and later runs build on it, it lists them and offers a fresh branch from where the run started, with the right attempt merged, registered as its own project. Your branch isn’t touched |
evolve run defect <run> --reason TEXT [--fixed-by SHA] |
records a bug found later in a finished run’s change (a defect). Use it when the pick between attempts wasn’t the mistake (that’s an overrule) but the checks and the review let the bug through. It’s shown on the run and counted as escaped_defect_rate |
evolve run approve-protected <run> --attempt N --path P [--path P] |
for an attempt rejected only because it changed protected files the goal needed it to change, like a test of the very thing the goal changes. It approves those edits and judges the attempt again, and that’s recorded with the run. Never for evolve.yaml, verification/ or what the checks run |
evolve run next [--repo R] [--agent A] [--yes] [--new-tests] [--read-tests] [--amend-tests] |
moves a roadmap along: merges the change for the goal just reached, then builds the next goal |
evolve run list [--limit N] [--repo R] [--objective O] [--state S] |
recent runs, or just one project’s, one goal’s, or those in one state |
evolve run show <run> [--json] |
a run’s attempts, evidence, decision and rollout |
evolve run plan <run> |
the run’s plan in full: every approach as the planner described it, how confident it was and why, what it found for the agents doing the work, and any way it suggests to split the goal |
evolve run activity <run> [--attempt N] [--tail N] [--full] |
what an attempt’s agent did, step by step: what it thought, said, ran and got back. For one that’s still going, watch its page on the Live view |
evolve run wait <run> [--timeout 30m] [--exit-status] |
waits for a run to finish. With --exit-status it exits 1 if the run didn’t end verified or succeeded, and 2 if it’s waiting on a person. Handy in scripts |
evolve events <run> [--after N] [--follow] [--json] |
the run’s record, entry by entry. Each line starts with its number; --after N shows only what came after it, and --follow keeps watching until the run ends |
evolve run cancel <run> [--reason T] |
stops a run. Anything it deployed is rolled back |
Approving and objecting
You can do the first two from a run’s page in the UI as well. Same result either way.
| Command | What it does |
|---|---|
evolve run approve <run> [--reason T] |
lets a supervised agent’s chosen change ship |
evolve run reject <run> --reason T |
refuses it |
evolve regret <deployment> --reason T |
reports that a promoted change turned out to be harmful after all. It counts against the agent, and against the checks that let it through |
evolve confidence [--json] |
the confidence review: indicators, autonomy, and what’s waiting for approval |
Asking questions
| Command | What it does |
|---|---|
evolve status [--environment E] [--json] |
what’s running where, and what should be |
evolve why <sha or digest> [--json] |
why that version exists, all the way back to the goal |
evolve decision replay <run> |
works the decision out again from the recorded evidence and confirms it matches |
evolve logs <digest> |
a check’s or attempt’s raw log |
evolve export <run> [--out DIR] |
writes the run’s evidence to files, signed |
evolve export verify <DIR> |
checks those signatures, anywhere |
Between machines
| Command | What it does |
|---|---|
evolve sync [--repo R] [--remote origin] [--no-push] |
swaps the record with a Git remote: fetch, merge, bring in new runs, push |
evolve reindex [--repo R] |
rebuilds Evolve’s database from the record in Git |
Housekeeping
evolve gc --older-than 720h [--apply] clears out after runs that closed before then: their working copies, their branches, and the program files built from them. It keeps anything an environment is still running or could fall back to. Unless you add --apply, it only lists what it would delete. And it never touches the record.
Running the server
The server is a separate program, evolve-server. Two of its commands are for whoever runs it, and both want the server and its worker (evolve-worker, the program that runs the agents and checks) stopped first. --config FILE points at the operator’s settings file, if it isn’t in the usual place.
| Command | What it does |
|---|---|
evolve-server rotate-key [--config FILE] [--distrust] |
swaps the key Evolve signs results with for a new one. Results signed with the old key still check out, unless you add --distrust because you think the old key leaked. Then they don’t, and runs still going have to be judged again |
evolve-server copy-store --from URL --to URL |
copies Evolve’s whole database into another, empty one, say from PostgreSQL to SQLite (two kinds of database). It checks the row counts match when it’s done |