CLI reference¶
Generated
This page is generated by scripts/build_docs.py from the installed worldline command:
the option tables come from the command definitions, the help blocks are the verbatim output of
uv run worldline <command> --help. Edit the command, not this page.
Every command prints the digests it produced, so two runs can be compared by eye.
Durations accept a unit suffix where noted (90s, 5m).
Commands¶
| Command | What it does |
|---|---|
worldline run |
Run the root (unperturbed) world and check its invariants. |
worldline explore |
Branch the world under fault schedules and record which branches violate invariants. |
worldline minimize |
ddmin a failing fault schedule down to a 1-minimal counterexample. |
worldline report |
Gather the output directory into index.json and typed agent evidence (never ATTESTED). |
worldline keygen |
Generate the kernel Ed25519 keypair. Commit only kernel_public.pem. |
worldline verify |
THE KERNEL: recompute every agent claim, attest matches, flag mismatches, seal and verify the bundle. |
worldline authorize |
Release gate: AUTHORIZED or DENIED from the sealed bundle, the policy and the public key. Exit 1 on DENIED. |
worldline demo |
Run the whole chain locally: explore, minimize, genome, challenge, report, verify, authorize (+ a DENIED demo). |
worldline genome |
Portable failure mechanisms. |
worldline genome extract |
Abstract a minimal counterexample into a portable failure mechanism. |
worldline genome challenge |
Instantiate a genome against another scenario (and immune controls) and see if it reproduces. |
worldline real |
Scenarios whose truth stream is real recorded public data (with provenance). |
worldline real usgs |
Fetch a USGS window (or reuse its snapshot), record provenance, and generate a real-data scenario. |
worldline http |
Run the pipeline against a real ASGI service (examples/service_demo). |
worldline http demo |
Root, explore, minimize and genome challenge against examples/service_demo over HTTP (ASGI). |
worldline resources |
Show (or copy out) the scenarios, invariants, policy and public key bundled with this install. |
worldline validate |
Check scenario YAML: schema, predicate DSL, references, and suspicious timings. |
worldline init |
Scaffold a commented scenario template that validates as-is. |
worldline¶
Usage: worldline [OPTIONS] COMMAND [ARGS]...
WORLDLINE: branch executions, isolate the causal difference, type the evidence, gate the release.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --version -V Show version, commit and Python, then exit. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
│ run Run the root (unperturbed) world and check its invariants. │
│ explore Branch the world under fault schedules and record which branches violate invariants. │
│ minimize ddmin a failing fault schedule down to a 1-minimal counterexample. │
│ report Gather the output directory into index.json and typed agent evidence (never │
│ ATTESTED). │
│ keygen Generate the kernel Ed25519 keypair. Commit only kernel_public.pem. │
│ verify THE KERNEL: recompute every agent claim, attest matches, flag mismatches, seal and │
│ verify the bundle. │
│ authorize Release gate: AUTHORIZED or DENIED from the sealed bundle, the policy and the public │
│ key. Exit 1 on DENIED. │
│ demo Run the whole chain locally: explore, minimize, genome, challenge, report, verify, │
│ authorize (+ a DENIED demo). │
│ genome Portable failure mechanisms. │
│ real Scenarios whose truth stream is real recorded public data (with provenance). │
│ http Run the pipeline against a real ASGI service (examples/service_demo). │
│ resources Show (or copy out) the scenarios, invariants, policy and public key bundled with this │
│ install. │
│ validate Check scenario YAML: schema, predicate DSL, references, and suspicious timings. │
│ init Scaffold a commented scenario template that validates as-is. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline run¶
Run the root (unperturbed) world and check its invariants.
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
SCENARIO |
path | yes | Scenario YAML. |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--out |
path | experiments/out |
Output directory. |
--invariants |
path | invariants |
--help output
Usage: worldline run [OPTIONS] {scenario}
Run the root (unperturbed) world and check its invariants.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
│ * scenario <path> Scenario YAML. [required] │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --out <path> Output directory. [default: experiments/out] │
│ --invariants <path> [default: invariants] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline explore¶
Branch the world under fault schedules and record which branches violate invariants.
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
SCENARIO |
path | yes |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--budget |
int | (required) | |
--seed |
int | (required) | |
--out |
path | experiments/out |
|
--strategy |
str | both |
guided | random | both |
--schedule-size |
int | 3 |
|
--invariants |
path | invariants |
--help output
Usage: worldline explore [OPTIONS] {scenario}
Branch the world under fault schedules and record which branches violate invariants.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
│ * scenario <path> [required] │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ * --budget <int> [required] │
│ * --seed <int> [required] │
│ --out <path> [default: experiments/out] │
│ --strategy <str> guided | random | both [default: both] │
│ --schedule-size <int> [default: 3] │
│ --invariants <path> [default: invariants] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline minimize¶
ddmin a failing fault schedule down to a 1-minimal counterexample.
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
EXPLORATION_JSON |
path | yes |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--out |
path | experiments/out |
|
--invariant |
str | decision.consistent_with_truth |
--help output
Usage: worldline minimize [OPTIONS] {exploration_json}
ddmin a failing fault schedule down to a 1-minimal counterexample.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
│ * exploration_json <path> [required] │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --out <path> [default: experiments/out] │
│ --invariant <str> [default: decision.consistent_with_truth] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline report¶
Gather the output directory into index.json and typed agent evidence (never ATTESTED).
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
OUT_DIR |
path | yes |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--code-commit |
str | (required) |
--help output
Usage: worldline report [OPTIONS] {out_dir}
Gather the output directory into index.json and typed agent evidence (never ATTESTED).
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
│ * out_dir <path> [required] │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ * --code-commit <str> [required] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline keygen¶
Generate the kernel Ed25519 keypair. Commit only kernel_public.pem.
Options
| Option | Type | Default | Description |
|---|---|---|---|
--out-dir |
path | policies |
|
--force |
flag | off |
--help output
Usage: worldline keygen [OPTIONS]
Generate the kernel Ed25519 keypair. Commit only kernel_public.pem.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --out-dir <path> [default: policies] │
│ --force │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline verify¶
THE KERNEL: recompute every agent claim, attest matches, flag mismatches, seal and verify the bundle.
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
OUT_DIR |
path | yes |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--signing-key |
str | Ed25519 private key PEM text or file path. (required) | |
--public-key |
path | (required) | |
--out |
path | Bundle JSON to write. (required) |
--help output
Usage: worldline verify [OPTIONS] {out_dir}
THE KERNEL: recompute every agent claim, attest matches, flag mismatches, seal and verify the
bundle.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
│ * out_dir <path> [required] │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ * --signing-key <str> Ed25519 private key PEM text or file path. [required] │
│ * --public-key <path> [required] │
│ * --out <path> Bundle JSON to write. [required] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline authorize¶
Release gate: AUTHORIZED or DENIED from the sealed bundle, the policy and the public key. Exit 1 on DENIED.
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
BUNDLE_JSON |
path | yes |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--policy |
path | policies/release.yaml |
|
--public-key |
path | policies/kernel_public.pem |
|
--artifact-digest |
str | (required) | |
--out |
path | (required) | |
--now |
str | ISO time to evaluate at (default: now). | |
--invalidate-assumption |
str | Revoke if any satisfying record rests on this assumption. |
--help output
Usage: worldline authorize [OPTIONS] {bundle_json}
Release gate: AUTHORIZED or DENIED from the sealed bundle, the policy and the public key. Exit 1
on DENIED.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
│ * bundle_json <path> [required] │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --policy <path> [default: policies/release.yaml] │
│ --public-key <path> [default: policies/kernel_public.pem] │
│ * --artifact-digest <str> [required] │
│ * --out <path> [required] │
│ --now <str> ISO time to evaluate at (default: now). │
│ --invalidate-assumption <str> Revoke if any satisfying record rests on this │
│ assumption. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline demo¶
Run the whole chain locally: explore, minimize, genome, challenge, report, verify, authorize (+ a DENIED demo).
Options
| Option | Type | Default | Description |
|---|---|---|---|
--out |
path | experiments/out |
|
--budget |
int | 150 |
|
--seed |
int | 42 |
|
--scenario |
path | scenarios/port_alert.yaml |
|
--challenge-scenario |
path | scenarios/convoy_lostlink.yaml |
|
--skip-tests |
flag | off | Do not run pytest for the tests:unit claim. |
--help output
Usage: worldline demo [OPTIONS]
Run the whole chain locally: explore, minimize, genome, challenge, report, verify, authorize (+ a
DENIED demo).
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --out <path> [default: experiments/out] │
│ --budget <int> [default: 150] │
│ --seed <int> [default: 42] │
│ --scenario <path> [default: scenarios/port_alert.yaml] │
│ --challenge-scenario <path> [default: scenarios/convoy_lostlink.yaml] │
│ --skip-tests Do not run pytest for the tests:unit claim. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline genome¶
Portable failure mechanisms.
--help output
Usage: worldline genome [OPTIONS] COMMAND [ARGS]...
Portable failure mechanisms.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
│ extract Abstract a minimal counterexample into a portable failure mechanism. │
│ challenge Instantiate a genome against another scenario (and immune controls) and see if it │
│ reproduces. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline genome extract¶
Abstract a minimal counterexample into a portable failure mechanism.
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
MINIMAL_JSON |
path | yes |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--out |
path | Output genome JSON file. (required) |
--help output
Usage: worldline genome extract [OPTIONS] {minimal_json}
Abstract a minimal counterexample into a portable failure mechanism.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
│ * minimal_json <path> [required] │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ * --out <path> Output genome JSON file. [required] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline genome challenge¶
Instantiate a genome against another scenario (and immune controls) and see if it reproduces.
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
GENOME_JSON |
path | yes | |
SCENARIO |
path | yes | Scenario to challenge. |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--seed |
int | 42 |
|
--out |
path | Output challenge JSON file. (required) | |
--immune |
path | Control scenario(s) expected NOT to reproduce. | |
--invariants |
path | invariants |
--help output
Usage: worldline genome challenge [OPTIONS] {genome_json} {scenario}
Instantiate a genome against another scenario (and immune controls) and see if it reproduces.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
│ * genome_json <path> [required] │
│ * scenario <path> Scenario to challenge. [required] │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --seed <int> [default: 42] │
│ * --out <path> Output challenge JSON file. [required] │
│ --immune <path> Control scenario(s) expected NOT to reproduce. │
│ --invariants <path> [default: invariants] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline real¶
Scenarios whose truth stream is real recorded public data (with provenance).
--help output
Usage: worldline real [OPTIONS] COMMAND [ARGS]...
Scenarios whose truth stream is real recorded public data (with provenance).
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
│ usgs Fetch a USGS window (or reuse its snapshot), record provenance, and generate a real-data │
│ scenario. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline real usgs¶
Fetch a USGS window (or reuse its snapshot), record provenance, and generate a real-data scenario.
Options
| Option | Type | Default | Description |
|---|---|---|---|
--start |
str | Window start, UTC ISO (e.g. 2025-07-29T23:20:00Z). (required) | |
--end |
str | Window end, UTC ISO. (required) | |
--minmag |
float | Minimum magnitude for the FDSN query. (required) | |
--out |
path | Scenario YAML (default scenarios/real/usgs_ |
|
--snapshot-dir |
path | data/real/usgs |
|
--offline |
flag | off | Regenerate from the existing snapshot, no network. |
--threshold |
float | 8.5 |
MODEL: magnitude threshold of the decision rule. |
--decision-at |
int | MODEL: decision time in s after window start (default: just after the first rule-flipping correction). |
--help output
Usage: worldline real usgs [OPTIONS]
Fetch a USGS window (or reuse its snapshot), record provenance, and generate a real-data scenario.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ * --start <str> Window start, UTC ISO (e.g. 2025-07-29T23:20:00Z). [required] │
│ * --end <str> Window end, UTC ISO. [required] │
│ * --minmag <float> Minimum magnitude for the FDSN query. [required] │
│ --out <path> Scenario YAML (default scenarios/real/usgs_<window>.yaml). │
│ --snapshot-dir <path> [default: data/real/usgs] │
│ --offline Regenerate from the existing snapshot, no network. │
│ --threshold <float> MODEL: magnitude threshold of the decision rule. │
│ [default: 8.5] │
│ --decision-at <int> MODEL: decision time in s after window start (default: just │
│ after the first rule-flipping correction). │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline http¶
Run the pipeline against a real ASGI service (examples/service_demo).
--help output
Usage: worldline http [OPTIONS] COMMAND [ARGS]...
Run the pipeline against a real ASGI service (examples/service_demo).
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
│ demo Root, explore, minimize and genome challenge against examples/service_demo over HTTP │
│ (ASGI). │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline http demo¶
Root, explore, minimize and genome challenge against examples/service_demo over HTTP (ASGI).
Options
| Option | Type | Default | Description |
|---|---|---|---|
--budget |
int | 60 |
|
--seed |
int | 42 |
|
--out |
path | experiments/out_http |
|
--scenario |
path | scenarios/port_alert.yaml |
Scenario whose injects are the truth stream. |
--genome |
path | experiments/out/genome.json |
Genome extracted by the simulator pipeline. |
--invariants |
path | invariants |
|
--schedule-size |
int | 3 |
--help output
Usage: worldline http demo [OPTIONS]
Root, explore, minimize and genome challenge against examples/service_demo over HTTP (ASGI).
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --budget <int> [default: 60] │
│ --seed <int> [default: 42] │
│ --out <path> [default: experiments/out_http] │
│ --scenario <path> Scenario whose injects are the truth stream. │
│ [default: scenarios/port_alert.yaml] │
│ --genome <path> Genome extracted by the simulator pipeline. │
│ [default: experiments/out/genome.json] │
│ --invariants <path> [default: invariants] │
│ --schedule-size <int> [default: 3] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline resources¶
Show (or copy out) the scenarios, invariants, policy and public key bundled with this install.
Options
| Option | Type | Default | Description |
|---|---|---|---|
--json |
flag | off | Machine-readable output. |
--copy-to |
path | Copy the bundled data into this directory (a ready working dir). | |
--overwrite |
flag | off | With --copy-to: replace existing files. |
--help output
Usage: worldline resources [OPTIONS] COMMAND [ARGS]...
Show (or copy out) the scenarios, invariants, policy and public key bundled with this install.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --json Machine-readable output. │
│ --copy-to <path> Copy the bundled data into this directory (a ready working dir). │
│ --overwrite With --copy-to: replace existing files. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline validate¶
Check scenario YAML: schema, predicate DSL, references, and suspicious timings.
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
SCENARIOS |
path | no | Scenario YAML file(s) to validate. |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--invariants |
path | Invariants directory or file to resolve the scenario's invariants: ids against [default: invariants/ if present]. |
|
--example |
flag | off | Print a minimal valid scenario and exit. |
--strict |
flag | off | Treat warnings as errors. |
--json |
flag | off | Print the reports as JSON. |
--help output
Usage: worldline validate [OPTIONS] [scenarios]...
Check scenario YAML: schema, predicate DSL, references, and suspicious timings.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
│ scenarios <path> Scenario YAML file(s) to validate. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --invariants <path> Invariants directory or file to resolve the scenario's `invariants:` │
│ ids against . │
│ --example Print a minimal valid scenario and exit. │
│ --strict Treat warnings as errors. │
│ --json Print the reports as JSON. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
worldline init¶
Scaffold a commented scenario template that validates as-is.
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
PATH |
path | yes | Where to write the new scenario YAML. |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--id |
str | Scenario id [default: the file name stem]. | |
--force |
flag | off | Overwrite an existing file. |
--help output
Usage: worldline init [OPTIONS] {path}
Scaffold a commented scenario template that validates as-is.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
│ * path <path> Where to write the new scenario YAML. [required] │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --id <str> Scenario id . │
│ --force Overwrite an existing file. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯