CLI Reference — doctor, evolve, apply, gate, report, autopilot, benchmark

Command	Description	Read-Only?	Notes
geneclaw doctor	Health check	✓ Always	Safe to run anytime. No side effects.
geneclaw evolve	Generate evolution proposal	✓ Dry-run default	Creates GEP JSON; does not apply.
geneclaw gate	Run 5-layer Gatekeeper	✓ Always	Validates proposal; no filesystem changes.
geneclaw apply	Apply gated proposal	❌ Requires `--apply`	Without `--apply`, simulates only.
geneclaw report	Generate reports	✓ Always	Reads event store; no side effects.
geneclaw autopilot	Multi-cycle autonomous loop	Configurable	Respects `dry_run` and risk thresholds.
geneclaw benchmark	Run performance benchmarks	✓ Read-mostly	Writes benchmark results to benchmarks/.

geneclaw doctor

Read-only health check. Verifies your environment, configuration, and dependencies. Safe to run at any time with no side effects.

geneclaw doctor [OPTIONS]

Options:
  --config   PATH    Path to geneclaw.toml (default: ./geneclaw.toml)
  --verbose          Show extended diagnostic output
  --json             Output as JSON

Examples:
geneclaw doctor
geneclaw doctor --verbose
geneclaw doctor --json | jq .nanobot_version

geneclaw evolve

Observe the event store, run diagnosis, and generate a dry-run evolution proposal (GEP JSON). Does not apply any changes.

geneclaw evolve [OPTIONS]

Options:
  --dry-run          Generate proposal only, no apply (default: true)
  --cycles    N       Number of evolve cycles to run (default: 1)
  --mode      MODE    Diagnosis mode: heuristic|llm (default: heuristic)
  --config   PATH    Path to geneclaw.toml
  --output   DIR     Output directory for proposals (default: proposals/)
  --verbose          Verbose output

Examples:
geneclaw evolve --dry-run
geneclaw evolve --mode llm --cycles 3
geneclaw evolve --output /tmp/proposals/

geneclaw gate

Run the 5-layer Gatekeeper on a proposal. Always read-only — no files are modified. Returns exit code 0 if the proposal passes all layers.

geneclaw gate [OPTIONS]

Options:
  --proposal  PATH   Path to GEP JSON file (required)
  --verbose          Show per-layer results
  --json             Output gate result as JSON

Examples:
geneclaw gate --proposal proposals/gep-001.json
geneclaw gate --proposal proposals/gep-001.json --verbose
geneclaw gate --proposal proposals/gep-001.json --json | jq .gate_passed

Exit codes:
0  — Gate passed (all 5 layers)
1  — Gate failed (at least one layer rejected)
2  — Configuration error

geneclaw apply

Apply a gated proposal. Requires the --apply flag for actual filesystem changes. Without --apply, performs a dry simulation only.

geneclaw apply [OPTIONS]

Options:
  --proposal  PATH   Path to GEP JSON file (required unless --rollback)
  --apply            REQUIRED to actually apply changes to disk
  --rollback         Rollback the most recent applied proposal
  --branch   NAME   Override git branch name (default: geneclaw/gep-{id})
  --verbose          Verbose output

Examples:
geneclaw apply --proposal proposals/gep-001.json          # simulation only
geneclaw apply --proposal proposals/gep-001.json --apply  # actually applies
geneclaw apply --rollback                                  # rollback last
geneclaw apply --rollback --proposal proposals/gep-001.json

# IMPORTANT: --apply is required for any filesystem changes
# Without it, apply only simulates and reports what would happen

geneclaw report

Generate human-readable or machine-readable reports from the event store. Always read-only.

geneclaw report [OPTIONS]

Options:
  --last      N       Show last N proposals (default: 10)
  --format   FMT    Output format: table|json|markdown (default: table)
  --since    DATE   Filter events since date (ISO 8601)
  --type     TYPE   Filter by event type
  --output   FILE   Write report to file

Examples:
geneclaw report --last 5
geneclaw report --format json --output report.json
geneclaw report --since 2025-01-01 --type gate_decision
geneclaw report --last 1 --format markdown

geneclaw autopilot

Run multiple evolve-gate-apply cycles autonomously. Respects dry_run and only auto-applies proposals within the configured risk threshold. Pauses for human review when risk exceeds the threshold.

geneclaw autopilot [OPTIONS]

Options:
  --cycles      N   Max number of cycles (default: from config)
  --max-risk    N   Override max risk for auto-approval (0-100)
  --dry-run         Run all cycles in dry-run mode (no apply)
  --interval   S   Seconds between cycles (default: from config)
  --config  PATH   Path to geneclaw.toml

Examples:
geneclaw autopilot --cycles 5 --dry-run
geneclaw autopilot --max-risk 20 --cycles 3
geneclaw autopilot --interval 30

geneclaw benchmark

Run performance benchmarks and compare against a baseline. Results are written to the benchmarks/ directory.

geneclaw benchmark [OPTIONS]

Options:
  --baseline  PATH  Path to baseline benchmark file
  --output    DIR   Output directory (default: benchmarks/)
  --format   FMT   Output format: json|table (default: json)
  --runs      N     Number of benchmark runs (default: 3)

Examples:
geneclaw benchmark
geneclaw benchmark --baseline benchmarks/pre-gep-001.json
geneclaw benchmark --runs 5 --format table

Global Flags

These flags apply to all commands:

--config   PATH    Path to geneclaw.toml (default: ./geneclaw.toml)
--version          Print version and exit
--help             Print help for command
--no-color         Disable colored output (useful in CI)

Geneclaw CLI Reference