Skip to main content

Bundle Entry: docs/spec/CLI_TOOLING_BUNDLE_v0.1.md

Genesis CLI v0.2 (Exit Codes + JSON)

This document is normative for the genesis CLI behavior in GenesisCode v0.2.

Global Flags

  • --json: emit exactly one JSON object on stdout for all subcommands.
    • In JSON mode, stderr is reserved for unexpected process-level failures (it should usually be empty).
  • --step-limit <N>: set the kernel evaluation step limit for commands that evaluate CoreForm.
    • Applies to: eval, explain, debug *, run, replay, test, apply-patch, semantic-edit *, fmt --engine selfhost, and eval --engine selfhost.
    • The step limit also applies to prelude initialization for that command.
    • Exception: for fmt --engine selfhost and eval --engine selfhost, toolchain bootstrap load is not charged against the step limit.
    • The v0.2 toolchain default is 5_000_000 steps.
  • --no-step-limit: disable the kernel evaluation step limit (for trusted inputs only).
    • For package commands (test, apply-patch), package.toml may reject this via [limits].allow_unlimited = false (default).
  • --max-pair-cells <N>: maximum total number of pair/cons cells allocated during evaluation.
  • --max-vec-len <N>: maximum observed vector length (vector literals and vec/push).
  • --max-map-len <N>: maximum observed map length (map literals, map/put, map/merge).
  • --max-bytes-len <N>: maximum observed bytes length (bytes literals and bytes/concat).
  • --max-string-len <N>: maximum observed string length in UTF-8 bytes (string literals and str/concat).
  • --selfhost-only: enforce strict selfhost frontend mode.
    • Also enabled when GENESIS_SELFHOST_ONLY=1|true|yes|on.
    • In this mode:
      • commands with --engine must use --engine selfhost
      • --selfhost-bootstrap must be artifact-only
      • commands outside the routed set return verification exit code 50.
      • docs/status/SELFHOST_CUTOVER.md (generated by genesis selfhost-dashboard) is the canonical routed/default command-coverage source; semantic implementation/authority maturity is reported separately in docs/status/SELFHOST_AUTHORITY_v0.1.md.
    • Current routed set:
      • native: fmt, eval, explain, debug/*, run, replay, optimize, typecheck, test, apply-patch, semantic-edit, pack, verify, selfhost-artifact, selfhost-dashboard, cli-schema, agent-index, agent-plan, bench/* (source-checkout profile), keygen, sign, transparency-verify, store/*, refs/*, commit/*, pkg/* (alias: gcpm/*), policy/*, sync/*, gc/*, vcs/*.
      • WASI: fmt, eval, explain, debug/*, run, replay, optimize, typecheck, test, apply-patch, semantic-edit, pack, verify, selfhost-artifact, selfhost-dashboard, cli-schema, agent-index, agent-plan, keygen, sign, transparency-verify, store/*, refs/*, commit/*, pkg/* (alias: gcpm/*), policy/*, sync/*, gc/*, vcs/*.
  • Runtime commands that resolve --engine selfhost must use an explicit pinned artifact identity (--selfhost-artifact, GENESIS_SELFHOST_TOOLCHAIN_ARTIFACT, or workspace genesis.workspace.toml -> [defaults].toolchain), and --selfhost-bootstrap artifact-only; implicit filesystem fallback discovery is rejected.
    • Applies to: fmt, eval, explain, debug *, run, replay, optimize, and vcs hash.
  • Package/frontend commands without an explicit engine (typecheck, test, apply-patch, pack) default to the selfhost frontend.
    • Production binaries require an explicit toolchain artifact pin:
      • --selfhost-artifact <path>, or
      • GENESIS_SELFHOST_TOOLCHAIN_ARTIFACT=<path>, or
      • genesis.workspace.toml -> [defaults].toolchain = "<path>".
    • Implicit filesystem discovery (./.genesis/selfhost/toolchain.gc, selfhost/toolchain.gc) is parity-harness-only behavior and must not be relied on in production workflows.
  • Kernel module evaluation uses the compiled evaluator by default and fails closed on compilation errors.
  • Tree-walk evaluation is reserved for explicit parity harnesses and is not a mainline CLI execution mode.

Runtime Backend Build Profiles

genesis production builds define explicit runtime backend feature profiles:

  • profile-headless (default): no first-party GPU/desktop host backends.
  • profile-gpu: enables gpu-device-backend.
  • profile-gfx: enables gfx-desktop-backend.
  • profile-backend: enables both backends.

Normative profile contract: - docs/spec/RUNTIME_BACKEND_PROFILES_v0.1.md

Rust Engine Compatibility Mode (Historical Comparisons Only)

--engine rust and --coreform-frontend rust exist solely to support deterministic parity checks against prior Rust semantics during the selfhost cutover.

Normative boundary and enforcement details are defined in: - docs/spec/SELF_HOST_BOUNDARY.md.

They are disabled by default and require explicit opt-in in development/debug profiles: - use dedicated parity binaries: - target/debug/genesis_parity - target/debug/genesis_wasi_parity

Release builds reject --engine rust and --coreform-frontend rust unconditionally.

CI must keep production binaries (genesis, genesis_wasi) rust-engine-free and run parity/golden comparisons through dedicated parity harnesses (e.g. scripts/selfhost_strict_smoke.sh / scripts/selfhost_strict_golden.sh).

Dedicated compatibility harness entrypoints: - debug parity harness binaries: - target/debug/genesis_parity - target/debug/genesis_wasi_parity - release-profile rejection gate: - scripts/selfhost_release_profile_guard.sh - This script must pass while release binaries still reject rust engine/frontend paths.

Subcommands (Signing + Policy)

  • genesis fmt <file> [--check] [--engine rust|selfhost]
    • when --engine is omitted, engine defaults to selfhost.
    • --engine rust remains available for parity/comparison workflows.
    • --engine selfhost runs the self-hosted CoreForm toolchain inside the kernel and therefore honors --step-limit/--no-step-limit.
    • JSON output includes data.selfhost_artifact (null for rust engine, otherwise {path,hash,source}).
  • genesis eval <file> [--engine rust|selfhost] [--stage1-pipeline] [--stage1-gate] [--stage2-gate]
    • when --engine is omitted, engine defaults to selfhost (same rule as fmt).
    • --engine selfhost runs self-hosted parse+canonicalize in-kernel before evaluation.
    • --stage1-pipeline runs Stage-1 CoreForm->CoreForm transforms before evaluation.
    • --stage1-gate enforces core/obligation::stage1-validation for the eval input.
    • --stage2-gate enforces core/obligation::translation-validation in fail-closed mode: unsupported modules fail the gate, and supported modules must validate successfully.
    • For Stage-2 gating, validation input is Stage-1 transformed CoreForm (matching package translation-validation flow), even when --stage1-pipeline is not requested.
    • JSON output includes data.selfhost_artifact (null for rust engine, otherwise {path,hash,source}).
    • JSON output includes data.kernel_eval_backend ("compiled").
  • genesis explain <file> --contract <expr-or-symbol> --msg <coreform> [--engine rust|selfhost]
    • when --engine is omitted, engine defaults to selfhost.
    • --engine selfhost runs self-hosted parse/canonicalize for the input module and self-hosted parse for --contract/--msg.
    • JSON output includes data.kernel_eval_backend ("compiled").
  • genesis debug <step|break|inspect|continue|frames|timeline> <file> --contract <expr-or-symbol> --msg <coreform> [--engine rust|selfhost] [...]
    • deterministic trace-debug command family over core/contract::explain artifacts.
    • step: advances a cursor by --count and returns selected frame.
    • break: finds first frame matching --match-key / --match-value.
    • inspect: returns frame at --index.
    • continue: advances to EOF or first matching breakpoint predicate.
    • frames: returns deterministic frame window (--start, --limit).
    • timeline: emits deterministic cross-layer timeline windows and optional canonical timeline artifacts (--out) combining dispatch steps with optional planner/typecheck/optimize JSON envelopes and effect-log boundaries.
      • optional layer inputs: --planner-json, --typecheck-json, --optimize-json, --effect-log.
    • all debug commands emit trace_hash_hex and optional canonical trace artifact via --trace-out.
    • genesis debug bisect --baseline <timeline.gc> --candidate <timeline.gc>:
      • deterministically returns first mismatching frame index/layer between two timeline artifacts.
    • JSON output kinds:
      • genesis/debug-step-v0.1
      • genesis/debug-break-v0.1
      • genesis/debug-inspect-v0.1
      • genesis/debug-continue-v0.1
      • genesis/debug-frames-v0.1
      • genesis/debug-timeline-v0.1
      • genesis/debug-bisect-v0.1
  • genesis run <file> --caps <policy.toml> [--log <out.gclog>] [--engine rust|selfhost]
    • when --engine is omitted, engine defaults to selfhost.
    • --engine selfhost runs self-hosted parse/canonicalize before evaluating the effect program.
    • JSON output includes data.kernel_eval_backend ("compiled").
  • genesis replay <file> --log <log.gclog> [--store <dir>] [--engine rust|selfhost]
    • when --engine is omitted, engine defaults to selfhost.
    • --engine selfhost runs self-hosted parse/canonicalize before replaying against the deterministic log.
    • exits successfully when the complete log verifies, including when the reproduced terminal value is a sealed ERROR; only replay parsing, integrity, protocol, or execution mismatches fail the replay command.
    • JSON output includes data.kernel_eval_backend ("compiled").
  • genesis selfhost-artifact --out <file> [--min-stage2-supported-modules <N>] [--min-stage2-validated-modules <N>]
    • emits a canonical self-host toolchain artifact used by --engine selfhost bootstrap.
    • runs Stage-1 + Stage-2 validation for each embedded selfhost module and records per-module gate metadata.
    • exits with code 30 when validation fails or configured Stage-2 minimum thresholds are not met.
  • genesis selfhost-dashboard [--markdown <file>] [--store <dir>]
    • emits a cutover dashboard artifact (genesis/selfhost-cutover-dashboard-v0.2) into a content-addressed store path.
    • writes a markdown mirror (default: docs/status/SELFHOST_CUTOVER.md) with routed/default command coverage only; it does not establish semantic selfhost authority or bootstrap closure.
    • semantic implementation/authority maturity is generated from the capability ledger in docs/status/SELFHOST_AUTHORITY_v0.1.md.
  • genesis cli-schema
    • emits machine-readable command/option schema for agent planning.
    • output kind: genesis/cli-schema-v0.1.
    • schema contract: docs/spec/CLI_JSON_SCHEMAS_v0.1.md (CLI Schema Contract section).
  • genesis agent-index
    • emits AI-facing planning index that bundles CLI schema, capability indices, default obligations, and reference workflow pointers.
    • output kind: genesis/agent-index-v0.1.
    • schema contract: docs/spec/AGENT_INDEX_v0.1.md.
  • genesis agent-plan --intent <agent-intent.json|-> --caps <caps.toml> [--max-workflows <n>]
    • emits a deterministic workflow DAG from structured intent (genesis/agent-intent-v0.1).
    • performs capability policy precheck before execution planning and returns deterministic failure taxonomy with repair hints when not policy-closed.
    • output kind: genesis/agent-plan-v0.1.
    • schema contract: docs/spec/AGENT_INDEX_v0.1.md (Agent Plan v0.1).
  • genesis bench <inspect|run|validate-run|score|replay|bundle|submit> ...
    • canonical transport-neutral GenesisBench execution surface; exact arguments and invariants are in docs/spec/GENESISBENCH_FRONT_DOOR_v0.1.md.
    • output kind: genesis/bench-v0.1; the exact operation result kind is in data.kind.
    • current v0.1 authority discovery requires a source checkout containing scripts/lib/genesisbench_front_door.py; the future self-host cutover must preserve the same contracts without broadening authority.
    • schema contract: docs/spec/GENESISBENCH_FRONT_DOOR_v0.1.md and its linked JSON Schemas.

CI strict selfhost gates: - scripts/selfhost_strict_smoke.sh: fast strict routing health check. - scripts/selfhost_strict_golden.sh: strict golden sweep across tests/spec/coreform/* and tests/spec/pkg_* fixtures, including WASI strict checks for available routed commands. - genesis keygen --out <key.toml>: generate an Ed25519 signing key (see docs/spec/SIGNING.md). - genesis sign --pkg <package.toml> --key <key.toml> [--acceptance <hex>] [--signatures <file>]: - sign the acceptance artifact hash and write a signature artifact into the evidence store - update .genesis/last_signature and the signature set file (default .genesis/signatures.gc) - genesis verify --pkg <package.toml> [--policy <policy.toml>] [--signatures <file>]: - when --policy is provided, enforce signature policy (see docs/spec/REGISTRY_POLICY.md) - genesis transparency-verify --pkg <package.toml>: verify the local transparency log chain (see docs/spec/TRANSPARENCY_LOG.md) - genesis optimize <file> [--engine rust|selfhost] ... - when --engine is omitted, engine defaults to selfhost (same rule as fmt). - genesis semantic-edit index --pkg <package.toml> --module-path <path> - emits a deterministic canonical AST node index with stable semantic node IDs. - output kind: genesis/semantic-edit-index-v0.1. - genesis semantic-edit workspace-graph --pkg <package.toml> - emits a deterministic workspace symbol graph with cross-module dependency edges. - output kind: genesis/semantic-edit-workspace-graph-v0.1. - genesis semantic-edit refactor-plan --pkg <package.toml> --kind <rename|move|extract> --from <symbol> --to <symbol> [--target-module-path <path>] - invokes the artifact-loaded GenesisCode core/cli::refactor-plan authority with no host planner fallback, then independently verifies the closed report. - emits conflict previews and a minimized, machine-mergeable multi-file semantic patch plan. - output kind: genesis/semantic-edit-refactor-plan-v0.1. - normative protocol: docs/spec/SEMANTIC_REFACTOR_PLAN_v0.1.md. - genesis semantic-edit apply-plan --pkg <package.toml> --kind <rename|move|extract> --from <symbol> --to <symbol> [--target-module-path <path>] [--caps <caps.toml>] - executes verified deterministic plan+apply in one command, returning workspace-wide conflict diagnostics when unsafe and obligation-gated transactional apply artifacts when safe. - output kind: genesis/semantic-edit-apply-plan-v0.1. - genesis vcs hash --in <file> [--engine rust|selfhost] - when --engine is omitted, engine defaults to selfhost (same rule as fmt). - JSON output includes data.selfhost_artifact (null for rust engine, otherwise {path,hash,source}). - genesis commit new --target-kind <package|module|contract|workspace> --target-id <string> --base <snapshot-hash-or-ref> --patch <patch-hash-or-file> --message <string> [--why <string>] [--obligation <sym> ...] [--evidence <hash> ...] [--author <string>] [--sign <key-id>] [--store] - genesis commit show <commit-hash> - Non-gcpm command schema IDs are enumerated in docs/spec/CLI_JSON_SCHEMAS_v0.1.md. - genesis gcpm ... is a first-class alias to genesis pkg ... and must preserve identical JSON kind contracts. - See docs/spec/GCPM_BUNDLE_v0.1.md. - Command schema IDs are enumerated in docs/spec/GCPM_JSON_SCHEMAS_v0.1.md. - Workspace lifecycle commands: - genesis gcpm new initializes genesis.workspace.toml + genesis.lock. - genesis gcpm scaffold --archetype <web|service|desktop|mobile|xr-game|data-ai> --name <workspace> [--root <dir>] [--runtime-backend <headless|gpu|gfx|backend>] [--force] bootstraps deterministic archetype project skeletons (workspace, package, caps policies, deploy presets, and AI-friendly starter module). - genesis gcpm add <name>@<selector> supports deterministic selectors: commit:<hex>, snapshot:<hex>, refs/... (or ref:refs/...), and semver:<range> (resolved against refs/tags/* with deterministic tag selection policy). - genesis gcpm update [--only <dep> ...] supports selective deterministic upgrades and emits machine-readable update rationale in command output. - genesis gcpm remove <dep> removes dependency requirements deterministically. - genesis gcpm migrate --pkg package.toml migrates package-only repos to workspace+lock form. - genesis gcpm build --pkg <package.toml> --target <web|desktop|service|ios|android|edge|service-runtime> [--out-dir <path>] emits deterministic immutable executable target bundles with build_manifest.gc, provenance.gc, and target artifact surfaces (artifact/package.*, artifact/package.*.sig, artifact/entrypoint.gc, artifact/launch_*.gc). Launch adapters are canonical CoreForm contracts (:gcpm/target-exec-adapter) that pin signature checks plus deterministic :boot/:smoke verification lanes. - genesis gcpm abi --pkg <package.toml> exports a deterministic contract ABI/introspection index including contract op tables, type/effect signatures, required capabilities, and manifest obligations. - genesis gcpm test --pkg <package.toml> is a gcpm alias for package obligation execution. - genesis gcpm run <task> executes canonical workspace tasks from genesis.workspace.toml (no shell glue). Built-ins: test, pack, build, typecheck, lint, run, bench, hash-pinned contract, eval, fmt, optimize. - cmd = "contract" tasks require --contract-h <hex64> in task args; gcpm run verifies file hash before execution. - genesis gcpm env --profile <dev|ci|release> [--runtime-backend <headless|gpu|gfx|backend|profile-*>] [--hydrate] realizes deterministic profile artifacts under .genesis/env/<profile-hash>/, including profile/workspace/lock/caps/dependency/member state required for reproducible workspace execution. - --hydrate fetches missing locked artifacts deterministically through policy-gated core/store::get before materialization. - genesis gcpm bridge --ecosystem <crates|npm|pypi|...> --name <pkg> --version <version> --source <coordinate> --source-hash <hex64> --key-id <key-id> --public-key <hex64> [--lock <path>] [--dep-name <name>] [--registry <alias>] converts external ecosystem coordinates into signed GenesisPkg commit/snapshot artifacts, emits replayable conversion evidence, and can pin mirrored provenance/evidence into a lock file. - genesis gcpm self-optimize --pkg <package.toml> [--dry-run] runs a closed-loop propose/optimize/validate/apply flow and only promotes rewrites when core/obligation::translation-validation and package obligations succeed. - genesis gcpm profile-runtime [--out <path>] [--history <path>] [--min-history <n>] [--max-regression-percent <n>] [--no-history-append] [--task-budget-us <n>] [--io-budget-us <n>] [--memory-budget-us <n>] emits deterministic non-gfx runtime profile artifacts (:task-scheduler, :io-store-cycle, :memory-pressure) and enforces absolute + p95 regression budgets in fail-closed mode. - genesis gcpm trace --pkg <package.toml> --requirements <requirements.gc> --snapshot <hex64> [--commit <hex64>] [--policy <hex64>] [--out <path>] [--no-store] emits deterministic :requirements-trace evidence for protected release traceability gates. --commit is optional to support pre-commit evidence generation without commit/evidence hash cycles. - genesis gcpm qualify [--commit <hex64>] --snapshot <hex64> [--policy <hex64>] --profile <name> --requirement <id>... --test-artifact <id=run-manifest-hex64>... --tool <name=path>... [--out <path>] [--no-store] emits deterministic :tool-qualification evidence for protected release qualification gates. - genesis gcpm assurance-pack --pkg <package.toml> --assurance-profile <custom|do178c-dal-a|do178c-dal-b|nasa-class-a|nasa-class-b|iec62304-class-c> --snapshot <hex64> [--commit <hex64>] [--policy <hex64>] [--trace <path-or-hash>] [--qualification <path-or-hash>] [--coverage <path-or-hash> ...] [--object-equivalence <path-or-hash>] [--independence-attestation <left:right@attestor> ...] [--independent-verifier-run <path-or-hash> ...] [--bundle-dir <dir>] [--out <path>] [--no-store] emits deterministic :assurance-pack evidence with profile-gated trace/tool/coverage/object-equivalence/independent-verifier checks and optional reproducible audit-bundle mirror. standards crosswalk and policy-pack templates are defined in docs/spec/ASSURANCE_PROFILE_PACKS_v0.1.md, docs/spec/ASSURANCE_STANDARDS_CROSSWALK_v0.1.md, docs/spec/ASSURANCE_STANDARDS_CROSSWALK_v0.1.json, and policies/assurance/profile_packs.toml. - ABI/introspection schema: docs/spec/GCPM_JSON_SCHEMAS_v0.1.md (GCPM ABI Contract section). - Workspace/env/build target schemas are consolidated in: - docs/spec/GCPM_JSON_SCHEMAS_v0.1.md - docs/spec/GCPM_BUNDLE_v0.1.md - Assurance evidence schemas: docs/spec/ASSURANCE_ARTIFACTS_v0.1.md. - JSON output for test includes data.kernel_eval_backend_default = "compiled". - genesis gcpm add|remove|lock|update|run|build|install|verify|doctor|env|publish|bridge|self-optimize --json emit deterministic AI workflow reports under data.report. - See docs/spec/GCPM_WORKFLOW_REPORTS_v0.1.md. - genesis gcpm --json emits prompt-safe deterministic telemetry under data.telemetry. - See docs/spec/GCPM_JSON_SCHEMAS_v0.1.md. - genesis gcpm doctor --caps <caps.toml> [--lock genesis.lock] - emits kind = "genesis/pkg-doctor-v0.1" with deterministic data.doctor diagnostics. - diagnostic schema is defined in docs/spec/GCPM_JSON_SCHEMAS_v0.1.md.

Exit Codes (Stable)

The CLI uses stable exit codes for automation and CI.

Code Meaning
0 Success
1 Internal error (bug/unexpected)
10 Parse/canonicalization error (CoreForm, TOML, patch/log schema)
11 Formatting check failed (fmt --check)
20 Evaluation / kernel error
30 Obligation or checker failure (test, typecheck, apply-patch when obligations fail)
40 Replay mismatch (replay)
41 Capability denied during run (at least one log entry has decision deny)
50 Verification failed (verify)
70 I/O error

Notes: - clap argument/usage errors are handled by clap itself and may exit with its own code. - run exits 41 if any capability request is denied, even if the program later handles the error as data. - replay may require --store <dir> if the .gclog externalizes large responses into an artifact store.

JSON Output (Stable Envelope)

All --json outputs use the same top-level envelope shape:

{
  "ok": true,
  "kind": "genesis/<command>-v0.2",
  "data": { },
  "error": null,
  "diagnostics_schema": "genesis/diagnostics-schema-v1",
  "diagnostics": []
}

On failure:

{
  "ok": false,
  "kind": "genesis/error-v0.2",
  "data": null,
  "error": {
    "code": "parse/coreform",
    "message": "…",
    "context": null
  },
  "diagnostics_schema": "genesis/diagnostics-schema-v1",
  "diagnostics": [
    {
      "version": "v1",
      "severity": "error",
      "code": "parse/coreform",
      "error_class": "parse",
      "message": "…",
      "exit_code": 10,
      "candidate_fix": "verify syntax and canonicalize with `genesis fmt --check <file>`.",
      "blocking_capability": null,
      "next_safe_action": "run `genesis fmt --check <file>` and retry once syntax/canonicalization issues are resolved.",
      "suggested_fix": "verify syntax and canonicalize with `genesis fmt --check <file>`."
    }
  ]
}

error.context is optional and may be omitted or null. diagnostics is always present in JSON output: - success cases: [] - failure cases: at least one typed diagnostic entry with stable code and exit_code - failure diagnostics always include machine-routeable remediation fields: - error_class (stable routing bucket) - candidate_fix (deterministic repair hint) - blocking_capability (string or null) - next_safe_action (safe retry/action instruction)

Conformance guard: - crates/gc_cli/tests/cli_diagnostics_matrix.rs enforces: - machine-actionable failure diagnostics across top-level command families - success envelopes with empty diagnostics for pure planning/report commands - drift detection against cli-schema top-level command names