Skip to content

CLI reference

Every command prints a ✓ or ✗ line per check and exits 0 on success, 1 on failure. Commands that print a report accept --json.

Command What it does
init Scaffold a contract that passes validate out of the box
validate Check a contract's structure, schema drift, examples, reference, spec vacuity and mutants; print the digest
schema Regenerate schema/*.json from schema.py
test Run a contract's spec against an implementation
digest Print a contract's content digest
impl-init Write an implementation manifest pinned to a contract's digest
keygen Create this runner's Ed25519 signing key
attest Run the spec in a sandbox and write a signed attestation
verify Check an attestation's signature, trust and digests; optionally reproduce it
diff Run several builds on one input pool and measure where they disagree
replicate Hand a pack to outside coding agents, then test, attest and diff their builds
pack validate Check a spec pack's brief, assumptions and obligations
mutants Show which checks kill which mutants, and the kill rate
canary plant Copy a contract for a builder with one example changed to contradict the spec
canary check Tell whether a build followed the spec or was fitted to the planted example
flag Report a part of the spec that contradicts itself, instead of coding around it

init

symbolon init CONTRACT_ID [--root contracts] [--author [email protected]]

Creates <root>/<namespace>/<name>/versions/1/ with every required file and a reference implementation. CONTRACT_ID looks like namespace/name: lowercase letters, digits and hyphens. Fails if the directory exists.

validate

symbolon validate PATH [--json]

Runs the checks listed in What symbolon validate checks and, if all pass, prints namespace/name@version sha256:<hex>. Contract code runs in a separate isolated Python process.

schema

symbolon schema PATH

Writes schema/input.json and schema/output.json from the Input and Output models in schema.py.

test

symbolon test PATH IMPL [--json]

Runs every example and property of the contract at PATH against IMPL, which is an implementation directory with symbolon-impl.toml or a single Python file. Failing properties print hypothesis's minimal failing case. This runs locally without a sandbox and signs nothing; use attest for evidence.

digest

symbolon digest PATH

Prints sha256:<hex> for a contract directory. See Digest for exactly what it covers.

impl-init

symbolon impl-init IMPL_DIR --contract CONTRACT_DIR [--entrypoint impl.py] [--author ...] [--license Apache-2.0]

Creates IMPL_DIR if needed and writes symbolon-impl.toml pinned to the contract's current digest. For implementations in other languages, edit the manifest to language = "command" and set command; see Implementations in other languages.

keygen

symbolon keygen [--out ~/.config/symbolon/runner.key]

Creates an Ed25519 key for this runner. The public key is written next to it as runner.pub. Share the .pub with anyone who should trust your attestations.

attest

symbolon attest CONTRACT IMPL [-o attestation.json] [--key ~/.config/symbolon/runner.key] [--sandbox auto|container|process]

Copies the contract and implementation into a fresh directory, checks that the implementation pins this contract's digest, runs the spec in a sandbox, and writes a signed in-toto attestation. Exits 0 if the result is PASSED. auto uses the container sandbox when Docker is reachable and the process sandbox otherwise. See Sandboxes.

verify

symbolon verify ATTESTATION [--trust KEY.pub ...] [--contract DIR] [--impl DIR] [--rerun] [--key ...] [--sandbox ...]
Option Checks
(none) The signature is valid and the statement is well-formed
--trust The signer is one of these keys. Repeat for several
--contract, --impl The attestation's digests match your local copies
--rerun Runs the spec again here and compares every check's outcome. Needs --contract and --impl

diff

symbolon diff CONTRACT IMPL IMPL... [--reference NAME] [--pool FILE ...] [--realistic FILE]
              [--mutations 500] [--property-cases 50] [--search 300] [--seed 0]
              [--weight NAME=W ...] [--severity TIER=W ...] [--max-ambiguity X]
              [--top 5] [-o report.json] [--json]

Runs every implementation on the same inputs: the contract's examples, inputs recorded from its property generators, mutated copies of both, any --pool files, and further mutations near each disagreement. It reports pairwise distances, the ambiguity of the ensemble with a 95% interval, behaviour classes, and the ways the builds split, largest first, each with a shrunk witness input and the obligations it traces to. Each IMPL is PATH or NAME=PATH; the name defaults to the build directory (rebuilds/go-1/search-query is go-1).

Option Effect
--reference Compare this implementation (the original product) with every build, but leave it out of the ensemble
--realistic A pool drawn to look like real use, reported as a separate estimate
--weight Ensemble weight of a build, default 1
--severity Cost of each disagreement tier: crash, value, format (default 1, 1, 0.1)
--max-ambiguity Exit 1 when the estimate is above this, for CI

Like test, it runs implementations in this process's environment, not a sandbox. See Measuring ambiguity.

replicate

symbolon replicate PACK [--agent NAME=COMMAND ...] [--builds 2] [--component NAME ...]
                   [--reference DIR] [--holdout DIR] [--holdout-seed N] [--holdout-scale 5]
                   [--attest | --no-attest] [--key PATH] [--sandbox auto] [--jobs 1]
                   [--agent-timeout 3600] [--prompt FILE] [--pool FILE ...]
                   [--mutations 500] [--property-cases 50] [--search 300] [--seed 0]
                   [--max-ambiguity X] [-o replication] [--json]

Gives a builder's copy of the pack at PACK to an outside coding agent once per build, then attests every component of every build, runs the holdout, and runs diff per component across the builds that passed. Symbolon does not build anything itself. Writes the builds, agent logs, attestations, diff reports and replication.json into the -o directory, which must not exist.

Option Effect
--agent The agent command, NAME=COMMAND or a bare COMMAND named after its program; repeat for several, and builds take turns. Default $SYMBOLON_AGENT, then Claude Code headless
--reference A directory with one implementation per component, such as a pack's oracle/: compared with every build, not part of the ensemble
--holdout A directory of <component>.jsonl examples the builders never see, run with --holdout-seed and --holdout-scale times the property cases
--no-attest Test each build instead of attesting it; no runner key needed
--jobs How many agents run at once
--prompt A prompt template instead of the default; $pack, $build and $components are filled in
--pool, --mutations, --property-cases, --search, --seed Passed to diff

Exits 1 when a build fails a component or its holdout, or a component's ambiguity is above --max-ambiguity. The agent runs with your permissions, outside the sandbox. See Replicating a pack.

pack validate

symbolon pack validate PATH [--json]

PATH is the pack directory holding symbolon-pack.toml. Checks the manifest, component digests, BRIEF.md sections, assumptions and obligations, then reports obligations by status and source. It does not run contract code; run validate on each component for that. See What symbolon pack validate checks.

mutants

symbolon mutants PATH [--mutants DIR] [--json]

Runs the spec against each mutant in PATH/mutants/, or in DIR (useful for measuring a contract without changing its digest), and lists the checks that kill each one. Ends with the checks that kill no mutant and the kill rate. Exits 1 if a mutant survives without SURVIVES. See Mutants.

canary plant

symbolon canary plant PATH OUT [--seed N] [--record FILE]

Copies the contract to OUT without reference/ and mutants/, and changes one example's expected output (chosen by --seed) to a value that still matches the output schema but contradicts the spec. Writes a private record, by default OUT.canary.json, next to the copy. Give the copy to a builder and keep the record. An honest build fails exactly that example.

canary check

symbolon canary check RECORD IMPL [--contract PATH] [--flags FILE] [--json]

Runs the finished build on the canary input. The outcome is gamed if it returns the planted output (the build was fitted to the examples), honest if it returns what the spec requires, and other otherwise. Also reports whether the builder flagged the canary example in symbolon-flags.jsonl next to the build. Exits 1 only for gamed. In a replication, drop gamed builds from the convergence evidence.

flag

symbolon flag REF REASON [--dir BUILD_DIR]

Appends {"ref", "reason", "flagged_at"} to BUILD_DIR/symbolon-flags.jsonl. REF is an obligation id, a check in pack form (search-query#example:40, search-query#test_name), or a bare example:<line>. Builders run this when an example and the description, or two checks, disagree, then build the reading they think is right. The flags file is part of the build directory, so it is covered by the implementation's digest.