Docs navigation

Developer Docs

CLI Reference

The valence-domains command groups: registry, analysis, scope/attest, bundles/audit, proposals.

valence-domains is the package's command-line entry point (installed with the base package). Commands below are grouped by job and verified against the parser in packages/valence_domains/cli/. Every command supports --help for its full flag list; the groups here cover the primary developer-facing workflows, not every flag on every command.

Surface map

Diagram: the CLI and the FastAPI backend are both built on the valence_domains package; a review pipeline strip runs a fort.14 pair through diff (producing typed deltas), gate (gate results), scope (a verdict), attest (a DSSE envelope), bundle create (a review bundle), and bundle verify.

Registry (discovery & validation)

  • validate [path] — Validate a manifest.toml: domain/mesh counts, missing mesh files, missing provenance on real-world meshes, and multi-mesh domains that need an explicit display_mesh.
    Example: valence-domains validate registry_data/manifest.toml
  • domains [--category] [--continent] [--application] — List domains, optionally filtered.
    Example: valence-domains domains --continent "Atlantic Ocean"
  • meshes [--domain] [--contributor] [--format] [--element-type] [--refinement-level] [--min-size] [--max-size] [--min-nodes] [--kind] [--test-case] — List meshes across all domains, optionally filtered.
    Example: valence-domains meshes --domain WNAT --kind mesh
  • show-domain <name> — Show one domain's fields and its meshes.
    Example: valence-domains show-domain WNAT
  • show-mesh <id> — Show one mesh's fields.
    Example: valence-domains show-mesh WNAT/hagen@v1

Analysis (gates, diff, identity, inspection)

  • gate [target] [--only] [--skip] [--threshold GATE.KEY=VAL] [--json] [--list] — Run Tier-1 structural gates on a fort.14. Hard gates (connectivity, boundary-closure) FAIL-block; angle and area-ratio gates WARN only — advisory.
    Example: valence-domains gate WNAT/hagen@v1 --json gate-report.json
  • diff <a> <b> [--tolerance] [--json] [--html] [--fort13 A13 B13] — Diff two fort.14 meshes into typed deltas (topological, geometric, bathymetric) and change regions.
    Example: valence-domains diff WNAT/hagen@v1 WNAT/onur@v1 --json diff.json
  • normalize <target> [--emit OUT.14] [--digest] — Canonicalize node and element ordering and print the normalized-v1 identity digest.
    Example: valence-domains normalize WNAT/hagen@v1 --digest
  • card <target> [--mesh] [--gate-report] [-o] [--json] [--interactive] — Generate a mesh-card YAML combining declared metadata with computed fields.
    Example: valence-domains card WNAT/hagen@v1 --mesh WNAT/hagen@v1
  • inspect <target> [--against] [--profile] [-o] [--json] [--tolerance] — Run the full inspection chain (gates, optional diff, and a mesh card) into one self-contained HTML report.
    Example: valence-domains inspect WNAT/hagen@v1 --against WNAT/onur@v1

Scope & attestation (change-scope verdicts)

See Trust, Provenance & Authority Boundaries for the L1/L2 distinction: without an ApprovedRegion, a scope verdict is L1 — advisory; bound to an approved-region-v1 artifact, it is L2 — enforcement-grade.

  • scope <a> <b> [--allow] [--bound] [--region] [--scope-file] [--json] [--evidence] — Check a mesh change against a declared scope. Advisory (L1) without an approved-region --scope-file; enforcement-grade (L2) with one.
    Example: valence-domains scope baseline.14 candidate.14 --allow geometry --bound geometry=5.0
  • attest <a> <b> ... --key KEY [--out] — Sign a scope verdict into an in-toto/DSSE envelope with an ed25519 private key. Verifiable artifact — cryptographically checkable, independent of the underlying verdict's L1/L2 authority level.
    Example: valence-domains attest baseline.14 candidate.14 --allow geometry --key priv.pem --out envelope.json
  • verify <envelope> --pubkey PUBKEY [--mesh-a] [--mesh-b] — Verify a DSSE attestation envelope and optionally re-bind it to the two mesh files. Verifiable.
    Example: valence-domains verify envelope.json --pubkey pub.pem --mesh-a baseline.14 --mesh-b candidate.14
  • keygen --out-priv OUT_PRIV --out-pub OUT_PUB — Generate an ed25519 keypair PEM pair for attest/verify.
    Example: valence-domains keygen --out-priv priv.pem --out-pub pub.pem

Bundles & audit chain (review evidence)

  • bundle create <artifact> [--against] [--card] [--chain] [--out] [--profile] [--tolerance] [--region] [--attestation] — Assemble a review bundle from a fort.14, optionally folding in a bound region's scope verdict. Derived artifact — not itself authoritative.
    Example: valence-domains bundle create WNAT/hagen@v1 --against WNAT/onur@v1 --out hagen.bundle
  • bundle approve <bundle> --actor SUBJECT --reason REASON [--yes] — Record a human ReviewApproved event into the bundle's chain. Authoritative, human-gated — fails closed without --yes or an interactive TTY confirmation.
    Example: valence-domains bundle approve hagen.bundle --actor reviewer@example.org --reason "structural gates pass" --yes
  • bundle export <bundle> --out OUT [--pdf] — Render the mesh-of-record appendix as HTML or PDF.
    Example: valence-domains bundle export hagen.bundle --out hagen.html
  • bundle verify <bundle> [--hmac-key] [--pubkey] [--attestation-pubkey] — Offline-verify a bundle's structure, digests, chain, signatures, and bindings. Verifiable artifact — the offline reviewer entry point.
    Example: valence-domains bundle verify hagen.bundle
  • audit log --chain PATH — Print the events in a §9 audit event chain.
    Example: valence-domains audit log --chain events.jsonl
  • audit verify --chain PATH [--hmac-key] [--pubkey] — Verify the hash-chain links (and optionally signatures) of an audit chain. Verifiable.
    Example: valence-domains audit verify --chain events.jsonl

Region proposals (planning → the human approval gate)

  • propose-region <baseline> --constraints CONSTRAINTS --artifact ARTIFACT [--artifact ...] [--set-id] [--output] — Build a ranked proposal set by importing one or more precomputed selection-artifact-v1 documents. Advisory — RegionProposals are structurally non-authoritative.
    Example: valence-domains propose-region baseline.14 --constraints constraints.json --artifact artifact.json
  • approve-region-proposal <proposal_set> --proposal-id ID --actor ACTOR --reason REASON — Approve one candidate proposal into an ApprovedRegion. Authoritative — the only artifact that crosses the enforcement boundary.
    Example: valence-domains approve-region-proposal proposal-set.json --proposal-id p1 --actor reviewer@example.org --reason "meets constraints"