Manual Completo da CLI, Subcomandos & Flags

Arquitetura e Filosofia da CLI

A interface de linha de comando do ChaosSQL foi projetada para engenheiros de sistemas que exigem feedback rápido, controle granular e integração transparente com scripts de automação e pipelines de CI/CD. Baseada na biblioteca Cobra e formatada pelo framework Lipgloss, a CLI oferece saída rica em terminal ANSI, cores tonais suaves do Design System do Studio Bregalda e geração de relatórios padronizados (SARIF, JUnit, HTML, OTEL, Mermaid).

Flags de Execução e Exportação

Flags aceitas por run e demo. --seed, --workers, --iterations e --fail-on valem só para o run; as três primeiras sobrescrevem os valores da spec. O jitter é definido na spec (engine.jitter_ms); o proxy tem flags próprias de jitter, barreira de commit e profundidade PCT (chaossql proxy --help). Os demais subcomandos documentam suas flags abaixo.

Referência dos Subcomandos

Os subcomandos mais usados estão abaixo. proxy, engine, swarm, mutate e server são cobertos em seus próprios capítulos ou com chaossql <comando> --help.

1. chaossql run <chaos.yaml>

Executa a bateria de testes de concorrência contra o arquivo de especificação informado:

# Execução padrão
chaossql run specs/banking_lost_update.yaml

# Execução com override de semente, workers e geração completa de relatórios
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 [cenário]

Executa uma das 10 demonstrações embutidas de anomalias de concorrência com terminal visual e 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>

Inicializa o servidor HTTP local para inspecionar um trace gravado previamente:

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

• --port int: Porta do servidor HTTP local (padrão 8090).
• --no-open bool: Não abre automaticamente o navegador padrão do sistema.

4. chaossql diff <spec.yaml>

Executa fuzzing diferencial cruzado comparando o comportamento de dois motores distintos com o mesmo workload e semente:

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

Cada motor roda no nível de isolamento da spec quando o suporta, e no próprio padrão caso contrário (o resumo informa). --fail-on-divergence retorna 1 quando os motores divergem; o chaossql swarm aceita a mesma flag.

5. chaossql replay <result.json>

Exibe o swimlane cronológico de eventos com marcações de microssegundos no terminal:

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

6. chaossql bench

Executa microbenchmarks de vazão do PRNG determinístico e do detector de ciclos Adya:

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

A vazão depende da máquina; rode no seu próprio hardware e compare os resultados ao longo do tempo, não contra um número publicado.

7. chaossql validate <chaos.yaml>

Linter estático que valida o esquema YAML, compila expressões dinâmicas de invariantes e verifica integridade referencial dos scripts SQL antes da execução:

chaossql validate specs/hospital_write_skew.yaml

8. chaossql init <caminho>

Gera o scaffolding inicial de um novo cenário com arquivos pré-configurados:

chaossql init novo_cenario --driver=postgres --name=auditoria_saldo --force

9. chaossql matrix

Gera uma matriz empírica completa baseada na taxonomia Hermitage (Martin Kleppmann), testando o banco alvo contra todas as 9 anomalias formais:

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

Códigos de Retorno do Processo (Exit Codes)

• 0: Nada para reprovar. Todas as invariantes se mantiveram, ou o --fail-on não selecionou o achado (--fail-on never; o demo sempre retorna 0, porque mostrar o bug é o papel dele).
• 1: Achado. Uma invariante foi violada (o padrão, --fail-on violation), o ChaosSQL Cloud apontou uma regressão (--fail-on regression), ou os motores divergiram com --fail-on-divergence (diff, swarm). Todos os relatórios pedidos são gravados antes.
• 2: Sem resposta confiável. Flags ou spec inválidas, falha de conexão do driver, erro de execução, execução encerrada como inconclusiva ou cancelada, ou --fail-on regression sem veredito do Cloud.

Assim, uma violação reprova o job de CI sozinha, e a GitHub Action reprova o step (input fail-on, padrão violation). Para reprovar só problemas novos enquanto os conhecidos são corrigidos, use --fail-on regression com o ChaosSQL Cloud, que compara cada pull request com a branch padrão.