Hillclimb CLI

Use the hillclimb CLI instead of hand-editing .hillclimb/ 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/hillclimb-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: hillclimb init, hillclimb validate, hillclimb run, hillclimb checkpoint, hillclimb restore, hillclimb ui, and hillclimb doctor. Bare hillclimb is help-only.
• For hillclimb validate and hillclimb run, .hillclimb/config.yaml is mandatory. hillclimb 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 hillclimb validate --workspace <path> --json when you need the planned run shape and readiness without creating .hillclimb/runtime/. Use hillclimb doctor when you need environment or adapter diagnostics and the config may still be missing.
• Treat .hillclimb/ 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 hillclimb run directly when you want to continue from current live edits; the runtime will auto-reconcile that workspace before trials when needed. Use hillclimb checkpoint only when you want to archive live edits without running the configured agent, eval, or strategy. Use hillclimb 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 Hillclimb-only CLI and skill surface. Those eval materials must stay generic to hillclimb.