Evolve CLI

Use the evolve CLI instead of hand-editing .evolve/ internals, inventing private archive commands, or treating the bundled Flow adapter as the whole product contract.

Treat this file as the thin agent-facing wrapper. The synced references are the source of truth for exact command syntax, config shape, validation loops, and example-runner guidance.

If you are reading the authored repo copy under skills/evolve-cli, the generated references/docs/ tree may not exist yet. In that case, use the canonical repo files under docs/. In the public install surface, that same content lives under references/docs/.

Working Rules

• Prefer the explicit public surface first: evolve init, evolve validate, evolve run, evolve checkpoint, evolve restore, evolve ui, and evolve doctor. Bare evolve is help-only.
• For evolve validate and evolve run, .evolve/config.yaml is mandatory. evolve init creates it, and those commands read it from the current directory or --workspace PATH. Keep top-level agent, eval, and strategy refs explicit and object-shaped with use.
• Use evolve validate --workspace <path> --json when you need the planned run shape and readiness without creating .evolve/runtime/. Use evolve doctor when you need environment or adapter diagnostics and the config may still be missing.
• Treat .evolve/ as private CLI-owned state. Inspect it when debugging, but do not hand-edit archive files unless the user explicitly wants that low-level recovery path.
• Use evolve checkpoint to keep live workspace edits as the new active candidate. Use evolve restore to discard live workspace edits or rewind active history.
• Prefer pnpm examples:list and pnpm example:run -- <example-name> when the user wants a real checked-in benchmark run or repro.
• Check the CLI guide before using bundled flow, harbor, or gepa adapter details; exact provider and runtime prerequisites live there.

Local References

• Read references/docs/cli.md for the canonical command and config guide. In the authored repo tree, the same content lives under docs/cli.md.
• Read references/docs/testing.md for product-local validation, example-runner, live-smoke, and release commands. In the authored repo tree, the same content lives under docs/testing.md.
• Use evals/evals.json together with evals/README.md when improving the shipped Evolve-only CLI and skill surface. Those eval materials must stay generic to evolve.