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
--generation-profile <name>	Generation budget profile (built-in or config alias)	Depth-derived
--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	reports/apophis/
--workspace	Run supported commands across workspace packages	false

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
--preset <name>	Preset name: safe-ci, platform-observe, llm-safe, protocol-lab
--force	Overwrite existing files
--noninteractive	Skip all prompts, require explicit flags

Examples:

apophis init --preset safe-ci
apophis init --preset llm-safe --force
apophis init --preset platform-observe --noninteractive

apophis verify

Run deterministic contract verification.

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

Flag	Description
--profile <name>	Profile name from config
--generation-profile <name>	Override generation budget for this run
--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
--format <mode>	Output format: human, json, ndjson, json-summary, ndjson-summary

Examples:

apophis verify --profile quick
apophis verify --routes "POST /users" --seed 42
apophis verify --changed
apophis verify --profile ci --routes "POST /users,PUT /users/*"

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:

apophis observe --profile staging-observe
apophis observe --check-config

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
--generation-profile <name>	Override generation budget for this run
--seed <number>	Deterministic seed (generated and printed if omitted)

Examples:

apophis qualify --profile oauth-nightly --seed 42
apophis qualify --profile lifecycle-deep
apophis qualify --profile oauth-nightly --generation-profile quick

You can define aliases in config:

export default {
  generationProfiles: {
    pr: 'quick',
    nightly: { base: 'thorough' },
  },
}

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:

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

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

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:

apophis doctor
apophis doctor --verbose

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:

apophis migrate --check
apophis migrate --dry-run
apophis migrate --write

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: scenario	enabled	enabled	enabled with allowlist	disabled by default
qualify: stateful	enabled	enabled	synthetic-only	disabled by default
qualify: chaos	enabled	enabled	canary-only	disabled by default
outbound mocks	enabled	enabled	allowlisted only	disabled by default
runtime throw-on-violation	optional	optional	exceptional	disabled by default

Operational rule: Production must never inherit qualify capabilities accidentally from a generic config file.