CLI Reference¶
The spo command is the primary entry point. Install with
pip install scpn-phase-orchestrator and the spo command becomes available.
Operational position¶
The CLI is the orchestration boundary between raw domain inputs and reviewable evidence. It is deliberately split into three planes:
- validation plane: binding parsing, schema checks, and resolved runtime defaults,
- execution plane: deterministic simulation, replayable audits, and proposal generation,
- reporting plane: deterministic summaries, regulator-oriented explanations, and transport checks.
A typical production workflow starts with spo doctor to confirm the
environment is ready, then spo validate, moves to spo inspect or spo run
on an accepted binding, and finally uses spo replay plus spo report before
any dashboard or platform review.
That separation keeps intent and actuation boundaries explicit. Even when the same user runs each command on one terminal session, each command has an independent evidence contract and explicit pass/fail output.
spo doctor¶
Check that the current environment can run the orchestrator: the interpreter
version, the required runtime dependencies, the optional native compute backends
(Rust spo_kernel, Julia juliacall, the Go toolchain or prebuilt shared
libraries, and the Mojo toolchain), and the optional feature extras (nn,
studio, queuewaves, plot, otel, notebook). It also checks the
package-local review/export adapter surfaces for FMI co-simulation and hybrid
co-compilation manifests. Run it first after any install, upgrade, or move to a
new host.
Options:
| Option | Description |
|---|---|
--json-out |
Emit the readiness record as a JSON audit object instead of text |
Exit codes:
| Code | Meaning |
|---|---|
| 0 | Interpreter in range and all required dependencies present |
| 1 | Interpreter out of range or a required dependency missing |
Missing optional backends and extras are reported as warnings and never change the exit code; only a missing required dependency or an unsupported interpreter fails the check. The probe imports no heavy optional packages and makes no network calls.
Example:
Example output (truncated):
SCPN Phase Orchestrator environment diagnostics — PASS
python 3.12.3 (Linux x86_64)
[ ok ] python Python 3.12.3 satisfies >=3.11,<3.14
[ ok ] numpy numpy 2.4.6
[ ok ] rust spo_kernel 0.5.10 importable (PyO3 FFI ready)
[ ok ] go prebuilt shared libraries: libhodge.so, libnpe.so, ...
[ ok ] fmi-cosimulation FMI 3.0 co-simulation export/review surface: ...
[warn] streamlit not installed — install the 'studio' extra
PASS: all required dependencies are present (... optional components available).
The JSON form (spo doctor --json-out) returns a stable record with overall
status, per-component checks, and missing_required / missing_optional
lists for CI gating and provisioning automation.
spo validate¶
Validate a binding specification YAML file against the schema.
Arguments:
| Argument | Description |
|---|---|
binding_spec |
Path to a binding_spec.yaml file |
Exit codes:
| Code | Meaning |
|---|---|
| 0 | Valid specification |
| 1 | Validation errors found |
Output: List of validation errors (one per line) or Valid followed by
the resolved binding configuration summary.
Example:
Example success output:
Valid
Resolved configuration:
domain: bio_stub v0.1.0 (research)
timing: sample=0.01s control=0.1s interval=10 steps
structure: layers=3 oscillators=6 channels=I, P, S
engine: kuramoto features=none
spo run¶
Run a simulation from a binding specification.
Arguments:
| Argument | Description |
|---|---|
binding_spec |
Path to a binding_spec.yaml file |
Options:
| Option | Default | Description |
|---|---|---|
--steps N |
100 | Number of integration steps |
--audit PATH |
None | Write audit log to JSONL file |
--seed INT |
None | RNG seed for reproducibility |
Output: Resolved binding configuration, then final R_good, R_bad, and
regime. If --audit is set, the audit header contains the same resolved
configuration summary under binding_summary (with backward-compatible
binding_config key).
Example:
spo replay¶
Replay an audit log and optionally verify deterministic reproducibility.
Arguments:
| Argument | Description |
|---|---|
audit_log |
Path to an audit.jsonl file produced by spo run --audit |
Options:
| Option | Default | Description |
|---|---|---|
--verify |
off | Verify deterministic reproducibility (rebuild engine from header, compare states) |
--output PATH |
None | Write verification report to JSON file |
Output: Step-by-step comparison with pass/fail verdict.
Example:
spo audit-detector¶
Audit any early-warning detector's event-vs-null skill from a JSON scores file, at a matched false-alarm rate with a label-permutation p-value. Reads a local file and prints JSON; it never actuates, signs, or reaches the network.
Arguments:
| Argument | Description |
|---|---|
scores_json |
JSON object with event_scores and null_scores arrays of per-segment scores (higher = more evidence of a transition) and an optional detector_name |
Options:
| Option | Default | Description |
|---|---|---|
--target-false-alarm |
0.10 | False-alarm rate the alarm threshold is held at or below |
--n-permutations |
10000 | Random relabellings drawn for the permutation p-value |
--seed |
0 | Seed of the permutation resampling |
--alpha |
0.05 | Significance level for the convenience beats-chance flag |
--corpus-id |
None | Corpus provenance identifier; with --captured-at seals the verdict |
--captured-at |
None | Caller-supplied audit timestamp; required (with --corpus-id) to seal |
--output PATH |
None | Also write the JSON record to this path |
Output: the audit verdict as JSON (matched threshold, achieved false alarm,
detection rate, permutation p-value); a hash-sealed record when --corpus-id and
--captured-at are both given. Malformed scores (missing key, empty, non-numeric,
non-finite) are rejected, never silently dropped.
Example:
spo audit-detector scores.json \
--target-false-alarm 0.10 \
--corpus-id grid-2026 --captured-at 2026-07-07T15:00:00+02:00
See the auditor API for the underlying package.
spo federated-transport-preflight¶
Build review-only federated transport evidence from node update audit records. The command reads newline-delimited node-update JSON records, wraps them in signed/hash-linked transport envelopes, replays the ordered batch, validates the transport declaration, and emits one deterministic preflight bundle. It does not open sockets, export raw data, or permit live transport execution.
Arguments:
| Argument | Description |
|---|---|
node_updates.jsonl |
JSONL node update audit records accepted by supervisor.federated_transport |
transport.json |
Transport declaration with transport, endpoint, owner/auth/TLS approval fields, or JSONL replay evidence |
Options:
| Option | Default | Description |
|---|---|---|
--output PATH |
None | Write the emitted preflight bundle JSON while also printing it to stdout |
Output: scpn_federated_transport_preflight_bundle_v1 JSON containing
envelopes, replay_ledger, preflight_manifest, and bundle_hash.
Example:
spo federated-transport-preflight updates.jsonl transport.json \
--output federated_transport_preflight.json
spo federated-secure-aggregation-preflight¶
Build review-only federated secure-aggregation evidence from node commitment records. The command reads newline-delimited node-commitment JSON records, builds the deterministic secure-aggregation manifest, validates custody/quorum evidence and operator approval from the deployment declaration, and emits one deterministic preflight bundle. It does not open sockets, export raw data, or permit live secure-aggregation execution.
Arguments:
| Argument | Description |
|---|---|
commitments.jsonl |
JSONL node commitment records accepted by supervisor.federated_secure_aggregation |
deployment.json |
Deployment declaration with optional aggregation policy plus quorum_evidence, custody_rotation_policy, custody_records, accepted_node_threshold, and operator approval fields |
Options:
| Option | Default | Description |
|---|---|---|
--output PATH |
None | Write the emitted preflight bundle JSON while also printing it to stdout |
Output: scpn_federated_secure_aggregation_preflight_bundle_v1 JSON containing
secure_aggregation_manifest, preflight_manifest, and bundle_hash.
Example:
spo federated-secure-aggregation-preflight commitments.jsonl deployment.json \
--output federated_secure_aggregation_preflight.json
spo federated-dp-noise-service-preflight¶
Build review-only federated DP noise-service evidence from a DP-noise request and a deployment declaration. The command builds the deterministic request and response manifests, validates deployment prerequisites (mechanism, custody, accountant, budget issuer, service endpoint, operator approval), and emits one deterministic preflight bundle. Missing prerequisites are reported as a not-ready readiness verdict rather than an error; only malformed inputs fail closed. It does not open sockets, generate live noise, or permit live DP noise-service execution.
Arguments:
| Argument | Description |
|---|---|
request.json |
DP-noise request with epsilon, delta, sensitivity, noise_multiplier, node_count, seed_hash, policy_keys, and per-node node_budgets |
deployment.json |
Deployment declaration with mechanism_label, privacy_accountant_owner, seed_custody_label, budget_issuer_label, service_endpoint_label, and operator_approved |
Options:
| Option | Default | Description |
|---|---|---|
--output PATH |
None | Write the emitted preflight bundle JSON while also printing it to stdout |
Output: scpn_federated_dp_noise_service_preflight_bundle_v1 JSON containing
request_manifest, response_manifest, preflight_manifest, deployment_ready,
and bundle_hash.
Example:
spo federated-dp-noise-service-preflight request.json deployment.json \
--output federated_dp_noise_service_preflight.json
spo evolutionary-policy-dsl-search¶
Run the deterministic offline policy-DSL mutation grammar over a compact policy-DSL source and emit a review-only candidate bundle. It does not actuate, merge, hot-patch, or execute any mutated candidate.
spo evolutionary-policy-dsl-search <policy.dsl> [--generations N] [--population N] [--mutation-step F] [--output PATH]
Output: scpn_evolutionary_grammar_review_bundle_v1 JSON with grammar
(policy-dsl), the offline search report, and bundle_hash.
spo evolutionary-petri-mutation¶
Run the deterministic offline Petri-net mutation grammar over a net-like JSON payload (object or record array) and emit a review-only candidate bundle.
spo evolutionary-petri-mutation <net.json> [--generations N] [--candidates-per-generation N] [--mutation-step F] [--max-arc-weight N] [--max-token-bound N] [--output PATH]
Output: scpn_evolutionary_grammar_review_bundle_v1 JSON with grammar
(petri), the offline mutation report, and bundle_hash.
spo evolutionary-topology-mutation¶
Run the deterministic offline topology mutation grammar over a topology JSON with
nodes and edges arrays and emit a review-only candidate bundle.
spo evolutionary-topology-mutation <topology.json> [--generations N] [--population N] [--mutation-step F] [--min-edge-weight F] [--max-edge-weight F] [--edge-add-base-weight F] [--max-add-candidates N] [--output PATH]
Output: scpn_evolutionary_grammar_review_bundle_v1 JSON with grammar
(topology), the offline mutation report, and bundle_hash.
spo assurance-case¶
Assemble a review-only assurance-case bundle from audit and evidence records.
Options:
| Option | Default | Description |
|---|---|---|
--audit-log PATH |
None | Add an audit-chain integrity evidence item from a JSONL audit log |
--evidence-file PATH |
None | Add JSON evidence records; repeatable |
--output PATH |
None | Write the bundle JSON instead of printing to stdout |
The command emits a deterministic scpn_assurance_case_bundle_v1 record with a
bundle hash, per-standard clause coverage summary, evidence items, conformance
records, and the regulatory disclaimer. The output is a technical
evidence-mapping aid; it does not permit actuation or claim compliance.
Example:
spo assurance-case --system grid-review \
--audit-log run.jsonl \
--evidence-file twin_confidence.json \
--output assurance_bundle.json
spo certification-evidence¶
Assemble a standards-shaped review package around the assurance-case bundle.
Options:
| Option | Default | Description |
|---|---|---|
--audit-log PATH |
None | Add an audit-chain integrity evidence item from a JSONL audit log |
--evidence-file PATH |
None | Add JSON evidence records; repeatable |
--output-dir DIR |
Required | Write manifest.json, assurance_bundle.json, and test_vectors.json |
The command refuses to write into a non-empty output directory. The manifest
seals the package with SHA-256 file digests, the assurance bundle hash, the
standards covered, and a package hash. test_vectors.json lets reviewers
recompute evidence content hashes and clause-rationale hashes without trusting
incidental file ordering.
Example:
spo certification-evidence --system grid-review \
--audit-log run.jsonl \
--evidence-file twin_confidence.json \
--output-dir review_package
spo koopman-mpc¶
Run the review-only dVOC oscillation-damping demonstration and emit the sealed
before/after PRC oscillation evidence when --output is set. The command builds
a local underdamped oscillator, fits a Koopman predictor, applies offline
Koopman-MPC damping, and maps both ringdowns to PRC-028-1 / PRC-030-1 review
evidence. It does not actuate a live plant.
Options:
| Option | Default | Description |
|---|---|---|
--frequency-hz HZ |
0.5 |
Natural oscillator frequency |
--damping-ratio ZETA |
0.02 |
Open-loop damping ratio |
--dt S |
0.02 |
Sampling interval in seconds |
--horizon N |
300 |
Ringdown steps for each pass |
--output PATH |
None | Write scpn_dvoc_oscillation_damping_audit_v1 JSON |
Example:
spo pmu-ieee-adapt¶
Convert an IEEE-format multi-header PMU concentrator CSV into the two-column
time_s,frequency_hz series the ringdown screener consumes. Phasor measurement
concentrators and the oscillation-detection literature export a wide layout — a
label row, a quantity-type row (T for time, F for frequency, VM/VA/IM/
IA for the phasor channels), a unit row, and a secondary-label row, then one
time column and five channels per unit. The command parses that layout, counts
each frequency channel's dropouts, selects the channel that is free of dropouts
and within --plausible-band-hz of the nominal frequency (breaking ties toward
the largest peak-to-peak swing, which carries the most oscillation content), and
writes the selected channel with a SHA-256 provenance line linking the derived
CSV back to the source capture. The derived CSV is then screened with
spo pmu-ringdown.
spo pmu-ieee-adapt <csv_path> <output_path> [--nominal-frequency-hz HZ] [--plausible-band-hz HZ] [--time-column NAME] [--frequency-column NAME]
Options:
| Option | Default | Description |
|---|---|---|
<csv_path> |
Required | IEEE-format multi-header PMU concentrator CSV |
<output_path> |
Required | Destination for the derived two-column ingester CSV |
--nominal-frequency-hz HZ |
60.0 |
Nominal grid frequency used to reject out-of-band channels |
--plausible-band-hz HZ |
2.0 |
Half-width in hertz of the accepted band about the nominal frequency |
--time-column NAME |
time_s |
Timestamp column name written to the derived CSV |
--frequency-column NAME |
frequency_hz |
Frequency column name written to the derived CSV |
Example:
spo pmu-ieee-adapt concentrator_capture.csv ringdown.csv \
--nominal-frequency-hz 60.0 \
--plausible-band-hz 2.0
spo pmu-ringdown ringdown.csv \
--event-id PMU-EVT-001 \
--captured-at 2026-07-04T10:00:00Z \
--signal-source PMU/BUS-42/frequency \
--analysis-rate-hz 5.0 \
--output pmu_prc.json
spo pmu-ringdown¶
Screen a local PMU or historian frequency ringdown CSV for PRC oscillation
review evidence. The command validates uniformly sampled finite frequency data,
subtracts the nominal grid frequency, mean-detrends the deviation to remove the
operating-point offset, optionally decimates an over-sampled capture, estimates
oscillation modes, and writes a hash-sealed scpn_pmu_ringdown_prc_audit_v1
record when --output is set. Timestamp uniformity is measured against the
best-fit uniform grid, so a capture exported with decimal-rounded timestamps is
accepted. The record keeps both the raw capture rate and the post-decimation
analysis rate.
spo pmu-ringdown <csv_path> --event-id ID --captured-at TIMESTAMP --signal-source LABEL [--nominal-frequency-hz HZ] [--detrend MODE] [--analysis-rate-hz HZ] [--output PATH]
Options:
| Option | Default | Description |
|---|---|---|
--event-id ID |
Required | Operator event identifier stamped into the evidence |
--captured-at TIMESTAMP |
Required | Capture timestamp stamped into the evidence |
--signal-source LABEL |
Required | PMU or historian signal label |
--time-column |
time_s |
Timestamp column in seconds |
--frequency-column |
frequency_hz |
Frequency column in hertz |
--nominal-frequency-hz HZ |
60.0 |
Nominal frequency subtracted before screening |
--detrend MODE |
mean |
Deviation detrend: mean removes the operating-point offset, none disables it |
--analysis-rate-hz HZ |
None | Decimate an over-sampled capture to this rate before estimation (about ten times the highest mode of interest) |
--output PATH |
None | Write the sealed JSON evidence record |
Example:
spo pmu-ringdown pmu_ringdown.csv \
--event-id PMU-EVT-001 \
--captured-at 2026-07-04T10:00:00Z \
--signal-source PMU/BUS-42/frequency \
--output pmu_prc.json
spo ibr-ride-through¶
Screen a local operator CSV for NERC PRC-029-1 ride-through review evidence.
The command reads timestamp, voltage, and frequency columns, applies the
review-only PRC-029 voltage/frequency screening tables, and writes a
hash-sealed scpn_ibr_ride_through_prc029_audit_v1 record when --output is
set. It does not actuate or certify compliance.
spo ibr-ride-through <csv_path> --event-id ID --captured-at TIMESTAMP --signal-source LABEL [--ibr-category other_ibr|ac_wind] [--output PATH]
Options:
| Option | Default | Description |
|---|---|---|
--event-id ID |
Required | Operator event identifier stamped into the evidence |
--captured-at TIMESTAMP |
Required | Capture timestamp stamped into the evidence |
--signal-source LABEL |
Required | Operator-facing IBR measurement source label |
--ibr-category |
other_ibr |
PRC-029 voltage table selector (other_ibr or ac_wind) |
--time-column |
time_s |
Timestamp column in seconds |
--voltage-column |
voltage_pu |
Voltage column in per unit |
--frequency-column |
frequency_hz |
Frequency column in hertz |
--output PATH |
None | Write the sealed JSON evidence record |
Example:
spo ibr-ride-through ride_through.csv \
--event-id IBR-EVT-001 \
--captured-at 2026-07-04T13:45:00Z \
--signal-source IBR-17/high-side-transformer \
--output prc029_ride_through.json
spo power-grid-prc-bundle¶
Bind the review-only dVOC, PMU ringdown, and IBR ride-through evidence files
into one assessor handoff package. The command verifies each child schema,
claim boundary, content hash, and source-file SHA-256 before writing
scpn_power_grid_prc_audit_bundle_v1. It is a packaging surface only: it does
not re-screen data, actuate, or certify compliance.
spo power-grid-prc-bundle --bundle-id ID --created-at TIMESTAMP --operator-context TEXT --dvoc-evidence PATH --pmu-ringdown PATH --ibr-ride-through PATH [--output PATH]
Options:
| Option | Default | Description |
|---|---|---|
--bundle-id ID |
Required | Operator bundle identifier |
--created-at TIMESTAMP |
Required | Bundle creation timestamp |
--operator-context TEXT |
Required | Human-readable assessor review context |
--dvoc-evidence PATH |
Required | scpn_dvoc_oscillation_damping_audit_v1 JSON |
--pmu-ringdown PATH |
Required | scpn_pmu_ringdown_prc_audit_v1 JSON |
--ibr-ride-through PATH |
Required | scpn_ibr_ride_through_prc029_audit_v1 JSON |
--output PATH |
None | Write the sealed bundle JSON |
Example:
spo power-grid-prc-bundle \
--bundle-id PG-REVIEW-001 \
--created-at 2026-07-04T15:10:00Z \
--operator-context "western interconnection post-event review" \
--dvoc-evidence dvoc_oscillation_damping.json \
--pmu-ringdown pmu_prc.json \
--ibr-ride-through prc029_ride_through.json \
--output power_grid_prc_bundle.json
spo scaffold¶
Scaffold a new domainpack directory with starter files.
spo scaffold <name>
spo scaffold <name> --llm --description "..."
spo scaffold <name> --llm --description "..." --llm-response-json proposal.json
Arguments:
| Argument | Description |
|---|---|
name |
Domain name (used as directory name under domainpacks/) |
Creates:
Example:
spo scaffold power_grid
spo scaffold traffic_grid --llm \
--description "I am modelling traffic lights in a 4-intersection grid"
LLM mode requires a configured provider through SPO_LLM_ENDPOINT and
SPO_LLM_MODEL, or an offline captured proposal via --llm-response-json.
The generated JSON proposal is normalised, converted to binding YAML, and
validated before any domainpack files are written.
spo report¶
Generate a coherence summary from an audit log.
Arguments:
| Argument | Description |
|---|---|
audit_log |
Path to an audit.jsonl file |
Options:
| Option | Default | Description |
|---|---|---|
--json-out |
off | Output as JSON instead of human-readable text |
Output: R_global statistics (mean, min, max, std), regime distribution (fraction of steps in each regime), and action counts.
Example:
spo explain¶
Generate a human-readable explanation report from an audit log.
Arguments:
| Argument | Description |
|---|---|
audit_log |
Path to an audit.jsonl file |
Options:
| Option | Default | Description |
|---|---|---|
--markdown-out PATH |
None | Write a Markdown explanation report |
--pdf-out PATH |
None | Write a dependency-free text PDF report |
--max-actions N |
12 | Maximum control actions to explain |
Output: regime distribution, regime transitions, metric evidence, control-action explanations, event summaries, and hash-chain status.
Example:
spo queuewaves serve¶
Start the QueueWaves cascade failure detection server.
Options:
| Option | Default | Description |
|---|---|---|
--config PATH |
None | QueueWaves YAML configuration file |
--host HOST |
0.0.0.0 |
Bind address |
--port PORT |
8080 |
Bind port |
Example:
spo queuewaves check¶
Run a one-shot health check against configured QueueWaves endpoints.
Options:
| Option | Default | Description |
|---|---|---|
--config PATH |
None | QueueWaves YAML configuration file |
Exit codes:
| Code | Meaning |
|---|---|
| 0 | All endpoints healthy |
| 1 | One or more endpoints degraded or unreachable |
Example:
Choosing commands by objective¶
Use this sequence when you need a production-level audit trail:
- validate that the domain spec is structurally correct,
- inspect resolved settings before any simulation run,
- execute with
--auditso later replay can confirm every step, - report and explain before handing results to operators.
Use spo run --audit for deterministic replay support.
Use spo replay --verify whenever a new dependency, backend, or host profile is
introduced.