CLI guide

CLI: operate GenOS without a hidden layer

The genos CLI is the reference boundary for humans, CI scripts, Studio, and the MCP server. It exposes genomes, snapshots, worlds, events, and experiments through structured output and stable exit codes.

Start here

cargo build -p genos-cli
export GENOS_BIN="$PWD/target/debug/genos"

$GENOS_BIN init
$GENOS_BIN --help

Three variables keep the binary, metadata, and working project separate:

• GENOS_BIN: executable path;
• GENOS_ROOT: .genos metadata store;
• GENOS_WORKSPACE_ROOT: base directory for isolated worlds.

Commands support --format json|yaml|text. Exit codes are 0 for success, 1 for a domain/runtime failure, 2 for invalid arguments, and 10 for a failed expectation, making the CLI suitable for CI gates.

Six essential command families

1. Agent

Create, inspect, and evolve a genome; execute a capsule; compute a diff; merge or replay a trajectory.

genos agent create --name reviewer --role verification --out reviewer.yaml
genos agent inspect reviewer.yaml --format json
genos agent mutate reviewer.yaml --drive caution=0.95 --out cautious.yaml
genos agent lineage --snapshot <ID>
genos agent replay --snapshot <ID>

2. Snapshot

Checkpoint state, then explicitly inspect or alter variables, memory, beliefs, and tool-call records.

genos snapshot save --capsule <ID> --out checkpoint.json
genos snapshot set-belief <SNAPSHOT> --key root_cause --probability 0.7
genos snapshot record-tool-call <SNAPSHOT> --tool cargo-test \
  --input '{}' --output '{"passed":true}'

3. World

Create an isolated directory or Git worktree, manipulate files inside it, compare worlds, and destroy the temporary environment.

genos world create --provider git-worktree --repo-root . --name hypothesis-a
genos world diff <WORLD_A> <WORLD_B>
genos world destroy <WORLD_ID>

4. Dev

Represent problem solving as a verifiable trajectory: diagnosis, hypothesis evidence, decisions, provenance, negative knowledge, adversarial review, and loop analysis.

genos dev diagnose "Deadlock under load" \
  --hypothesis "queue exhaustion" \
  --hypothesis "lock-order inversion"
genos dev search-failures "worker deadlock"
genos dev record-decision "Change lock order" --evidence tests/deadlock.log

5. Experiment

Run multi-world scenarios for refactoring, incidents, scientific investigation, security co-evolution, or unknown-cause debugging. These workflows are a research surface; check each scenario's evidence status before treating it as a guarantee.

6. Platform

Index documents, retrieve passages, and expose claim-level citations with the provider-neutral genos-platform crate.

genos platform ingest docs/ --index .genos/platform.json
genos platform search "How does replay work?" --index .genos/platform.json
genos platform status

Minimal CI flow

set -e
genos init
genos agent inspect genomes/reviewer.yaml --format json
genos diff baseline.json candidate.json --expect-changed-path state
genos agent replay --snapshot "$SNAPSHOT_ID"

The CLI becomes especially useful with MCP: MCP provides discovery and tool schemas, while the CLI preserves an inspectable, scriptable execution path.

Important maturity boundary

The presence of a subcommand does not always mean its full behavior is implemented. For example, genos hallucination detect|inject|test|extract|analyze|correct|simulate currently consists of command skeletons that print their intent. The mechanisms that are operational today are documented in Hallucination reduction.

See the full CLI manual and the Quickstart.