apophis-fastify/docs/cli.md

CLI Reference

Reference for APOPHIS CLI commands.

Global Flags

Every command accepts these flags:

Flag	Description	Default
--config <path>	Config file path	Auto-detect
--profile <name>	Profile name from config	First profile
--cwd <path>	Working directory override	process.cwd()
--format <mode>	Output format: human, json, ndjson, json-summary, ndjson-summary	human
--color <mode>	Color mode: auto, always, never	auto
--quiet	Suppress non-error output	false
--verbose	Enable verbose logging	false
--artifact-dir <path>	Directory for artifact output. Artifacts written on failure or when explicitly configured.	reports/apophis/
--workspace	Run supported commands across workspace packages	false

Note: json-summary and ndjson-summary are only supported by verify and qualify commands.

Commands

apophis init

Scaffold config, scripts, and example usage.

After scaffolding, run the shortest working path:

1. Install deps for your package manager (for example npm install fastify @fastify/swagger)
2. Run apophis doctor
3. Run apophis verify --profile <profile>

apophis init --preset safe-ci

Flag	Description
-p, --preset <name>	Preset name: safe-ci, platform-observe, llm-safe, protocol-lab
-f, --force	Overwrite existing files
--noninteractive	Skip all prompts, require explicit flags

Examples:

<!-- smoke-test -->
apophis init --help

apophis verify

Run deterministic contract verification.

apophis verify --profile quick --routes "POST /users"

Flag	Description
--profile <name>	Profile name from config
--routes <filter>	Route filter pattern (comma-separated, supports wildcards)
--seed <number>	Deterministic seed (generated and printed if omitted)
--changed	Filter to git-modified routes only
--workspace	Run across all workspace packages
--format <mode>	Output format: human, json, ndjson, json-summary, ndjson-summary

Examples:

<!-- smoke-test -->
apophis verify --help

Machine output for CI:

Use json-summary or ndjson-summary to reduce log volume:

# Concise JSON with summary only
apophis verify --profile quick --format json-summary

# Concise NDJSON with only run.started, run.summary, run.completed
apophis verify --profile quick --format ndjson-summary

apophis observe

Validate runtime observe configuration and reporting setup.

apophis observe --profile staging-observe

Flag	Description
--profile <name>	Profile name from config
--check-config	Only validate config, do not activate

Examples:

<!-- smoke-test -->
apophis observe --help

apophis qualify

Run scenario, stateful, protocol, or chaos-driven qualification.

apophis qualify --profile oauth-nightly --seed 42

Flag	Description
--profile <name>	Profile name from config
--seed <number>	Deterministic seed (generated and printed if omitted)

Examples:

<!-- smoke-test -->
apophis qualify --help

apophis replay

Replay a failure using seed and stored trace.

apophis replay --artifact reports/apophis/failure-2026-04-28T12-30-22Z.json

Flag	Description
--artifact <path>	Path to failure artifact
--route <pattern>	Replay only routes matching pattern

Examples:

<!-- smoke-test -->
apophis replay --help

apophis doctor

Validate config, environment safety, docs/example correctness.

apophis doctor [--mode verify|observe|qualify] [--strict]

Flag	Description
--mode <mode>	Filter checks to a specific mode
--strict	Treat warnings as failures
--workspace	Run across all workspace packages

Checks:

• Dependency checks (Fastify, swagger, Node version)
• Config validation (unknown keys, unsafe modes)
• Route discovery checks
• Docs/example smoke checks
• Legacy config detection
• Mixed config style detection

Examples:

<!-- smoke-test -->
apophis doctor --help

apophis migrate

Check and rewrite deprecated config or API usage.

apophis migrate --check

Flag	Description
--check	Detect legacy config without rewriting
--dry-run	Show exact rewrites without writing
--write	Perform rewrites

Examples:

<!-- smoke-test -->
apophis migrate --help

Common Tasks

CI workflow with machine output

apophis verify --profile ci --format json-summary --artifact-dir reports/apophis

Monorepo workspace verification

apophis verify --workspace --profile quick
apophis doctor --workspace

Replay a failure

apophis replay --artifact reports/apophis/failure-*.json

Gotchas

• --changed requires a git repository
• migrate defaults to --dry-run (safe by default)
• --workspace is fully implemented by verify and doctor. observe and qualify accept the flag but run in the current package only.
• Seeds ensure deterministic generation; handler nondeterminism (e.g., Date.now()) can still cause replay divergence

Exit Codes

Code	Meaning
0	Success
1	Behavioral / qualification failure
2	Usage, config, or environment safety violation
3	Internal APOPHIS error
130	Interrupted (SIGINT)

Environment Safety Matrix

Capability	local	test/CI	staging	prod
verify	enabled	enabled	optional	optional, usually off
observe	optional	optional	enabled	enabled
qualify	enabled	enabled	optional	disabled by default
chaos	enabled	enabled	optional	disabled by default
runtime throw-on-violation	optional	optional	exceptional	disabled by default

Notes:

• qualify is gated as a whole. The code does not distinguish scenario, stateful, and chaos sub-modes in environment policy.
• chaos on protected routes requires allowChaosOnProtected: true.
• observe blocking requires allowBlocking: true.
• Production must never inherit qualify capabilities accidentally from a generic config file.