CLI Manual, Subcommands & Flags

CLI Architecture & Design Philosophy

The ChaosSQL Command-Line Interface (CLI) is engineered for systems developers who demand rapid feedback loops, granular scheduling control, and frictionless integration with automated CI/CD pipelines. Built upon Cobra and styled with Charm Lipgloss, the CLI outputs expressive ANSI terminal diagnostics, soft tonal colors from the Studio Bregalda Design System, and exportable industry-standard artifacts (SARIF, JUnit XML, standalone HTML, OpenTelemetry OTLP JSON, and Mermaid sequence diagrams).

Execution and Export Flags

Flags accepted by run and demo. --seed, --workers, --iterations and --fail-on apply to run only; the first three override the values in the spec. Jitter is set in the spec (engine.jitter_ms); the proxy has its own jitter, commit barrier and PCT depth flags (chaossql proxy --help). Other subcommands document their own flags below.

Subcommand Reference

The most used subcommands are below. proxy, engine, swarm, mutate and server are covered in their own chapters or with chaossql <command> --help.

1. chaossql run <chaos.yaml>

Executes concurrency and invariant fuzzing against the provided specification file:

# Standard execution
chaossql run specs/banking_lost_update.yaml

# Execution with overrides and comprehensive multi-format report exports
chaossql run specs/banking_lost_update.yaml \
  --seed=42 \
  --workers=8 \
  --iterations=50 \
  --export-sarif=reports/audit.sarif \
  --export-html=reports/report.html \
  --export-junit=reports/junit.xml \
  --export-repro \
  --ui

2. chaossql demo [scenario]

Launches one of the 10 built-in reference demonstrations featuring terminal visualization and delta-debugging:

chaossql demo banking       # P4 Lost Update
chaossql demo inventory     # A3 Inventory Oversell
chaossql demo hospital      # A5B Hospital Write Skew
chaossql demo financial     # A5A Financial Read Skew
chaossql demo auction       # G0 Auction Dirty Write
chaossql demo crypto        # G1c Circular Information Flow
chaossql demo flash_crash   # G1a Flash Crash Dirty Read
chaossql demo ticket        # G2 Anti-Dependency Cycle
chaossql demo deadlock      # G-DL Mutual Lock Deadlock
chaossql demo fk            # Foreign Key Cascade Deadlock

3. chaossql ui <trace.json>

Starts the embedded HTTP web visualizer to inspect a previously recorded execution trace:

chaossql ui trace_dump.json --port=8090 --no-open

• --port int: Local HTTP listener port (default 8090).
• --no-open bool: Disables automatic launch of the system default web browser.

4. chaossql diff <spec.yaml>

Executes cross-engine differential fuzzing, comparing the runtime isolation semantics of two different database engines under identical workloads and seeds:

chaossql diff specs/lost_update.yaml \
  --driver-a=sqlite --dsn-a=":memory:" \
  --driver-b=postgres --dsn-b="postgres://user:pass@localhost:5432/testdb" \
  --seed=42

Each engine runs at the spec isolation level when it supports it, and at its own default otherwise (the summary says so). --fail-on-divergence exits 1 when the engines diverge; chaossql swarm takes the same flag.

5. chaossql replay <result.json>

Renders a microsecond-accurate terminal Gantt swimlane from a recorded execution trace:

chaossql replay result.json --max-events=100

6. chaossql bench

Executes throughput microbenchmarks measuring deterministic PRNG generation and Adya cycle detection speeds:

chaossql bench --duration=3s --workers=8 --json

Throughput depends on the machine; run it on your own hardware and compare results over time rather than against a published number.

7. chaossql validate <chaos.yaml>

Static linter that verifies YAML schema adherence, compiles invariant dynamic expressions, and validates relational referential integrity before runtime execution:

chaossql validate specs/hospital_write_skew.yaml

8. chaossql init <path>

Generates production-ready scaffolding for a new test scenario with pre-configured templates:

chaossql init new_scenario --driver=postgres --name=balance_audit --force

9. chaossql matrix

Executes an empirical matrix validation based on Martin Kleppmann's Hermitage test taxonomy, testing the target engine against all 9 formal isolation anomalies:

chaossql matrix --driver=postgres --dsn="postgres://user:pass@localhost:5432/testdb" --markdown

Process Exit Codes

• 0: No finding to fail on. Every invariant held, or --fail-on did not select the finding (--fail-on never; demo always exits 0, since showing the bug is its job).
• 1: Finding. An invariant was violated (the default, --fail-on violation), ChaosSQL Cloud reported a regression (--fail-on regression), or the engines diverged with --fail-on-divergence (diff, swarm). Every requested report is written first.
• 2: No trustworthy answer. Invalid flags or spec, driver connection failure, execution error, a run that ended inconclusive or canceled, or --fail-on regression without a Cloud verdict.

A violation therefore fails the CI job by itself, and the GitHub Action fails its step (input fail-on, default violation). To fail only on new problems while known ones are being fixed, use --fail-on regression with ChaosSQL Cloud, which compares each pull request with the default branch.