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 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.

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