Cashu Fault Lab
Browse documentation

Operate

CLI reference

Reference for lab commands, artifacts, and diagnostic workflows.

View sourceEdit on GitHub

Global diagnostic option: --json before a command emits machine-readable diagnostics for command-level failures.

cashu-fault-lab nutzap list

Exercise NIP-61 duplicate delivery, independent-wallet synchronization and durable recovery.

Modes: json Environment: None Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab nutzap run crash-after-swap --seed demo --output artifacts/nutzap.json
  • cashu-fault-lab nutzap replay artifacts/nutzap.json --seed demo

cashu-fault-lab nutzap run <scenario>

Exercise NIP-61 duplicate delivery, independent-wallet synchronization and durable recovery.

Arguments:

  • scenario: A packaged NIP-61 scenario ID.

Options:

  • --seed <seed>: Reproduction seed; only the hash is reported. Default: nutzap-demo.
  • --mint-url <url>: Disposable HTTP mint on 127.0.0.1; omitted means simulated evidence.
  • --cdk-receiver <path>: Native CDK receiver binary; requires --mint-url and adds cross-language matrix scenarios.
  • --output <path>: Write redacted JSON evidence.

Modes: json Environment: None Artifacts: --output JSON report

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab nutzap run crash-after-swap --seed demo --output artifacts/nutzap.json
  • cashu-fault-lab nutzap replay artifacts/nutzap.json --seed demo

cashu-fault-lab nutzap matrix

Exercise NIP-61 duplicate delivery, independent-wallet synchronization and durable recovery.

Options:

  • --seed <seed>: Reproduction seed; only the hash is reported. Default: nutzap-demo.
  • --mint-url <url>: Disposable HTTP mint on 127.0.0.1; omitted means simulated evidence.
  • --cdk-receiver <path>: Native CDK receiver binary; requires --mint-url and adds cross-language matrix scenarios.
  • --output <path>: Write redacted JSON evidence.

Modes: json Environment: None Artifacts: --output JSON report

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab nutzap run crash-after-swap --seed demo --output artifacts/nutzap.json
  • cashu-fault-lab nutzap replay artifacts/nutzap.json --seed demo

cashu-fault-lab nutzap replay <artifact>

Exercise NIP-61 duplicate delivery, independent-wallet synchronization and durable recovery.

Arguments:

  • artifact: Single-scenario redacted JSON report.

Options:

  • --seed <seed>: Reproduction seed; only the hash is reported. Default: nutzap-demo.
  • --mint-url <url>: Disposable HTTP mint on 127.0.0.1; omitted means simulated evidence.
  • --cdk-receiver <path>: Native CDK receiver binary; requires --mint-url and adds cross-language matrix scenarios.
  • --output <path>: Write redacted JSON evidence.

Modes: json Environment: None Artifacts: --output JSON report

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab nutzap run crash-after-swap --seed demo --output artifacts/nutzap.json
  • cashu-fault-lab nutzap replay artifacts/nutzap.json --seed demo

cashu-fault-lab up

Start the local lab services

Options:

  • --profile <profile>: Compose profile. Default: lab.

Modes: text Environment: None Artifacts: .cashu-fault-lab/runtime/reference/secrets.env

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab up --profile lab

cashu-fault-lab down

Stop the local lab services

Options:

  • --profile <profile>: Compose profile. Default: lab.

Modes: text Environment: None Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab down --profile lab

cashu-fault-lab adapter init --language <language> --name <name>

Scaffold a standalone wallet adapter project

Options:

  • --language <language>: Template language. Choices: typescript, rust, python.
  • --name <name>: Adapter project name.
  • --role <role>: Adapter role. Default: both. Choices: sender, receiver, both.
  • --output <path>: Output directory. Default: <name>.

Modes: text Environment: None Artifacts: <output>/adapter-manifest.json, <output>/Dockerfile, <output>/.github/workflows/ci.yml

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab adapter init --language rust --name my-wallet
  • cashu-fault-lab adapter init --language python --name receive-only --role receiver --output ./receive-only

cashu-fault-lab adapter preflight --adapters <path>

Run read-only readiness checks against loopback wallet adapters

Options:

  • --adapters <path>: Local adapter manifest.
  • --adapter <id>: Check only one registered adapter.
  • --profile <profile>: Profile readiness to inspect. Default: delivery-v1.
  • --json: Emit a machine-readable preflight report.

Modes: text, json Environment: <adapter token environment variables from the manifest> Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab adapter preflight --adapters adapter-manifest.json
  • cashu-fault-lab adapter preflight --adapters adapter-manifest.json --adapter my-wallet --json

cashu-fault-lab adapter preview --adapters <path>

Run a non-qualifying maintainer preview for one loopback adapter pair

Options:

  • --adapters <path>: Local adapter manifest.
  • --sender <id>: Sender adapter ID.
  • --receiver <id>: Receiver adapter ID.
  • --profile <profile>: Delivery profile. Default: delivery-v1.
  • --seed <seed>: Deterministic preview seed. Default: cashu-fault-lab-maintainer-preview.
  • --output-dir <path>: Preview result directory. Default: cashu-fault-results.

Modes: text Environment: <adapter token environment variables from the manifest>, CFL_HTTP_FAULT_GATEWAY_URL, CFL_HTTP_FAULT_GATEWAY_TOKEN Artifacts: <output-dir>/README.txt, <output-dir>/preflight.json, <output-dir>/preview.json, <output-dir>/preview.html, <output-dir>/preview.junit.xml

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab adapter preview --adapters adapter-manifest.json --sender my-wallet --receiver my-wallet

cashu-fault-lab demo

Run the response-loss recovery demo against the reference stack

Options:

  • --keep: Leave a stack started by this command running.
  • --seed <seed>: Deterministic demo seed. Default: cashu-fault-lab-v0.1.0-demo.
  • --artifact <path>: Write JSON evidence to this path.
  • --report <path>: Write HTML report to this path.

Modes: text Environment: None Artifacts: .cashu-fault-lab/runtime/reference/reports/demo.json, .cashu-fault-lab/runtime/reference/reports/demo.html

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab demo
  • cashu-fault-lab demo --seed cashu-fault-lab-v0.1.0-demo --artifact docs/examples/v0.1.0-demo.json --report docs/examples/v0.1.0-demo.html

cashu-fault-lab run <scenario>

Run one scenario

Arguments:

  • <scenario>: scenario JSON file path or packaged shorthand.

Options:

  • --seed <seed>: Deterministic seed. Default: cashu-fault-lab.
  • --artifact <path>: Write replayable result artifact.
  • --sender <adapter>: Sender adapter. Default: reference-ts.
  • --receiver <adapter>: Receiver adapter. Default: reference-ts.
  • --adapters <path>: External adapter manifest.
  • --verbose: Print progress for each command.

Modes: text Environment: CFL_CASHU_TS_TOKEN, CFL_CDK_TOKEN, CFL_REFERENCE_RECEIVER_TOKEN Artifacts: artifacts/latest.json

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab run retry/response-lost --seed demo
  • cashu-fault-lab run scenarios/retry/response-lost.json --artifact artifacts/run.json

cashu-fault-lab replay <artifact>

Replay a deterministic failure artifact

Arguments:

  • <artifact>: Artifact JSON file.

Options:

  • --artifact <path>: Write the new result artifact.
  • --verbose: Print progress for each command.

Modes: text Environment: None Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab replay artifacts/latest.json

cashu-fault-lab shrink <artifact>

Minimize a failing artifact to the smallest reproducing command set

Arguments:

  • <artifact>: Artifact JSON file.

Options:

  • --artifact <path>: Write the minimized result artifact.
  • --run-limit <count>: Maximum shrink probe runs. Default: 100.
  • --verbose: Print minimization progress.

Modes: text Environment: None Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab shrink artifacts/latest.json --run-limit 50

cashu-fault-lab diff <left> <right>

Compare two scenario result artifacts and print the structured differences

Arguments:

  • <left>: Left baseline artifact JSON file.
  • <right>: Right candidate artifact JSON file.

Options:

  • --json: Emit machine-readable JSON instead of text.
  • --suite <suite>: Limit checks to a lab suite. Default: all. Choices: all, lifecycle.

Modes: text, json Environment: None Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab diff artifacts/baseline.json artifacts/candidate.json --json

cashu-fault-lab matrix

Run the sender/receiver compatibility matrix

Options:

  • --profile <profile>: Matrix profile. Default: delivery-v1.
  • --seed <seed>: Deterministic seed. Default: cashu-fault-lab.
  • --min-passes <count>: Minimum passing pairs required.
  • --release-policy <path>: Release policy JSON file.
  • --release-suite <path>: Release scenario suite JSON file.
  • --adapters <path>: External adapter manifest.
  • --format <format>: Report format for full matrix output. Default: text. Choices: text, json, junit, html.
  • --output <path>: Write the formatted matrix report to a file.
  • --verbose: Print per-pair results.

Modes: text, json, junit, html Environment: CFL_CASHU_TS_TOKEN, CFL_CDK_TOKEN, CFL_REFERENCE_RECEIVER_TOKEN Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab matrix --profile delivery-v1
  • cashu-fault-lab matrix --profile delivery-v1 --format html --output artifacts/matrix.html

cashu-fault-lab report [artifact]

Render a redacted scenario report

Arguments:

  • [artifact]: Scenario result JSON file.

Options:

  • --format <format>: Report format. Default: json. Choices: json, junit, html.
  • --output <path>: Write report to a file.

Modes: json, junit, html Environment: None Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab report artifacts/latest.json --format html --output report.html

cashu-fault-lab ls

List all available scenarios

Options:

  • --json: Output JSON.

Modes: text, json Environment: None Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab ls --json

cashu-fault-lab inspect <scenario>

Pretty-print a scenario file

Arguments:

  • <scenario>: Scenario JSON file path or shorthand.

Modes: json Environment: None Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab inspect retry/response-lost

cashu-fault-lab validate <scenario>

Validate a scenario file against the scenario-spec schema

Arguments:

  • <scenario>: Scenario JSON file path or shorthand.

Modes: text Environment: None Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab validate retry/response-lost

cashu-fault-lab gen-id

Generate a random 128-bit ProtocolId

Modes: text Environment: None Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab gen-id

cashu-fault-lab doctor

Check local prerequisites (env, tools, ports) for funded lab lanes

Options:

  • --json: Emit machine-readable JSON instead of text.

Modes: text, json Environment: CFL_REAL_MINT_URL, CFL_CASHU_TS_TOKEN, CFL_CDK_TOKEN, CFL_REFERENCE_RECEIVER_TOKEN, CFL_REFERENCE_RECEIVER_CLAIM_KEY, CFL_HTTP_FAULT_GATEWAY_TOKEN Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab doctor
  • cashu-fault-lab doctor --json

cashu-fault-lab lifecycle run <scenario>

Run one wallet lifecycle fault scenario

Arguments:

  • <scenario>: Lifecycle scenario ID or JSON path.

Options:

  • --adapter <id>: Lifecycle adapter ID.
  • --mint <id>: Test mint identity.
  • --mint-url <url>: Override the scenario mint URL.
  • --seed <seed>: Deterministic seed supplied out of band for replay. Default: cashu-fault-lab-lifecycle.
  • --format <format>: Redacted lifecycle report format. Default: json. Choices: json, junit, html.
  • --output <path>: Write the lifecycle report.
  • --artifact <path>: Legacy JSON output alias.

Modes: json, junit, html Environment: CFL_LIFECYCLE_<ADAPTER>_URL, CFL_LIFECYCLE_<ADAPTER>_TOKEN, CFL_HTTP_FAULT_GATEWAY_URL, CFL_HTTP_FAULT_GATEWAY_TOKEN Artifacts: artifacts/lifecycle/<scenario>.json

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab lifecycle run mint-response-lost --adapter cashu-ts --mint nutshell-local --seed demo

cashu-fault-lab lifecycle matrix

Run the wallet lifecycle compatibility matrix

Options:

  • --profile <profile>: Lifecycle matrix profile. Default: wallet-lifecycle-v1.
  • --seed <seed>: Deterministic seed. Default: cashu-fault-lab-lifecycle.
  • --json: Emit machine-readable matrix results.
  • --output <path>: Write matrix output.

Modes: text, json Environment: CFL_LIFECYCLE_MATRIX_FILE Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab lifecycle matrix --profile wallet-lifecycle-v1 --json

cashu-fault-lab lifecycle replay <artifact>

Replay an exact wallet lifecycle failure

Arguments:

  • <artifact>: Redacted failure artifact JSON.

Options:

  • --seed <seed>: Original seed supplied out of band.
  • --adapter <id>: Lifecycle adapter ID.
  • --mint <id>: Test mint identity.

Modes: text Environment: CFL_LIFECYCLE_<ADAPTER>_URL, CFL_LIFECYCLE_<ADAPTER>_TOKEN Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab lifecycle replay artifacts/failure.json --seed demo --adapter cashu-ts --mint nutshell-local

cashu-fault-lab wallet-doctor collect (--relay <url> | --discover-from <url>)

Fetch NIP-60 events from relays and verify proofs against their mints

Options:

  • --relay <url>: Relay url; repeat for each relay.
  • --discover-from <url>: Bootstrap relay for kind 10019 / NIP-65 discovery; repeatable.
  • --nsec-env <var>: Env var holding the subject secret key.
  • --pubkey <hex>: Subject pubkey for keyless redacted capture.
  • --timeout-ms <ms>: Per-relay and per-mint timeout.
  • --output <path>: Write the capture bundle.

Modes: text Environment: CFL_NIP60_SUBJECT_KEY Artifacts: artifacts/wallet-doctor/capture.json

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab wallet-doctor collect --relay ws://127.0.0.1:4430 --relay ws://127.0.0.1:4431

cashu-fault-lab wallet-doctor diagnose <capture>

Explain why relays disagree about one wallet

Arguments:

  • <capture>: Capture bundle JSON.

Options:

  • --output <path>: Write the diagnosis artifact.
  • --format <format>: Diagnosis report format (json).

Modes: text, json Environment: None Artifacts: artifacts/wallet-doctor/diagnosis.json

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab wallet-doctor diagnose artifacts/wallet-doctor/capture.json

cashu-fault-lab wallet-doctor plan <capture>

Emit a dry-run repair plan with safety invariants

Arguments:

  • <capture>: Capture bundle JSON.

Options:

  • --output <path>: Write the repair plan artifact.

Modes: text Environment: None Artifacts: artifacts/wallet-doctor/plan.json

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab wallet-doctor plan artifacts/wallet-doctor/capture.json

cashu-fault-lab wallet-doctor check <capture>

CI gate: independently recapture, diagnose, and verify the safe repair plan

Arguments:

  • <capture>: Capture bundle JSON.

Options:

  • --nsec-env <var>: Env var holding the subject secret key.
  • --timeout-ms <ms>: Per-relay and per-mint timeout.
  • --output <path>: Write the combined check artifact.

Modes: text Environment: CFL_NIP60_SUBJECT_KEY Artifacts: artifacts/wallet-doctor/check.json (when --output is supplied)

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab wallet-doctor check artifacts/wallet-doctor/capture.json

cashu-fault-lab wallet-doctor run <scenario>

Run one wallet-doctor scenario against a live fixture/relay/mint stack

Arguments:

  • <scenario>: Packaged scenario id or relative JSON path.

Options:

  • --seed <seed>: Deterministic seed.
  • --output <path>: Write the scenario artifact.

Modes: text Environment: CFL_WALLET_DOCTOR_FIXTURE_URL, CFL_WALLET_DOCTOR_FIXTURE_TOKEN, CFL_WALLET_DOCTOR_RELAYS, CFL_WALLET_DOCTOR_RELAY_CONTROLS, CFL_WALLET_DOCTOR_RELAY_CONTROL_TOKEN Artifacts: artifacts/wallet-doctor/<scenario>.json

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab wallet-doctor run del-chain-break --seed demo

cashu-fault-lab wallet-doctor matrix

Run every packaged wallet-doctor scenario

Options:

  • --profile <profile>: Matrix profile (nip60-doctor-v1).
  • --seed <seed>: Deterministic seed.
  • --json: Emit machine-readable matrix results.
  • --output <path>: Write matrix output.

Modes: text, json Environment: CFL_WALLET_DOCTOR_FIXTURE_URL, CFL_WALLET_DOCTOR_FIXTURE_TOKEN, CFL_WALLET_DOCTOR_RELAYS Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab wallet-doctor matrix --profile nip60-doctor-v1 --json

cashu-fault-lab wallet-doctor replay <artifact>

Replay a wallet-doctor scenario artifact with its original seed

Arguments:

  • <artifact>: Scenario artifact JSON.

Options:

  • --seed <seed>: Original seed supplied out of band.

Modes: text Environment: CFL_WALLET_DOCTOR_FIXTURE_URL, CFL_WALLET_DOCTOR_FIXTURE_TOKEN, CFL_WALLET_DOCTOR_RELAYS Artifacts: None

Exit Codes:

  • 0: Command completed successfully.
  • 1: The lab operation completed with a failed scenario or gate.
  • 2: Command input, configuration, or environment was invalid.

Examples:

  • cashu-fault-lab wallet-doctor replay artifacts/wallet-doctor/del-chain-break.json --seed demo