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

```bash
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:**

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

### `apophis verify`

Run deterministic contract verification.

```bash
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:**

```bash
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:

```bash
# 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.

```bash
apophis observe --profile staging-observe
```

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

**Examples:**

```bash
apophis observe --profile staging-observe
apophis observe --check-config
```

### `apophis qualify`

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

```bash
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:**

```bash
apophis qualify --profile oauth-nightly --seed 42
apophis qualify --profile lifecycle-deep
```

### `apophis replay`

Replay a failure using seed and stored trace.

```bash
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:**

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

### `apophis doctor`

Validate config, environment safety, docs/example correctness.

```bash
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:**

```bash
apophis doctor
apophis doctor --verbose
```

### `apophis migrate`

Check and rewrite deprecated config or API usage.

```bash
apophis migrate --check
```

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

**Examples:**

```bash
apophis migrate --check
apophis migrate --dry-run
apophis migrate --write
```

## Common Tasks

### CI workflow with machine output
```bash
apophis verify --profile ci --format json-summary --artifact-dir reports/apophis
```

### Monorepo workspace verification
```bash
apophis verify --workspace --profile quick
apophis doctor --workspace
```

### Replay a failure
```bash
apophis replay --artifact reports/apophis/failure-*.json
```

## Gotchas

- `--changed` requires a git repository
- `migrate` defaults to `--dry-run` (safe by default)
- `--workspace` is only supported by `verify` and `doctor` commands
- 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.