# Command Reference

This document mirrors `src/index.ts` command registration and is the canonical CLI reference.

Trust boundary: live receipt > committed receipt > memory summary. Memory is advisory only; `8099/deploy` via git-proxy is the guarded deploy route, and `8098/deploy-webhook` is legacy/stale for fable-agent deploy trust.

Agent-manager rule: agents draft, receipts prove, humans approve, and only guarded `8099/deploy` may ship.

Agent-run traces follow system-card discipline: `fable.agent_run.trace.v1` records budget, environment, safety posture, receipts, latency, and `deployAttempted: false`; capability evidence is not deploy authority.

Last sync: 2026-06-14.

## Quick examples

```bash
fable-agent run "Review API security risks"
fable-agent session start "ship launch plan"
fable-agent skills list --tag security
fable-agent pai status
fable-agent fable5 stack "refactor module" --enable-plinius
fable-agent fusion run "summarize RFC" --openrouter
fable-agent plinius godmode "improve explanation quality"
```

## Top-level commands

`fable-agent <command> [subcommand] [options]`

| Command | Primary purpose |
|---|---|
| `run` | Execute full agent loop |
| `verify` | Emit agentic verification attestation |
| `attest` | Alias for `verify` |
| `session` | Session lifecycle |
| `skills` | Skill registry ops |
| `state` | Knowledge state / stats view |
| `security` | Security scanners |
| `cyber` | Read-only defensive cyber evidence collection |
| `pai` | PAI/bridge operations |
| `status` | Runtime surface summary |
| `workflow` | Load workflow JSON |
| `benchmark` | Run/view benchmark metrics |
| `cost` | Cost/usage reporting |
| `exa` | Exa search utilities |
| `demo` | Demo mode |
| `learned` | Summaries of learned material |
| `familiar` | Note capture and health graph |
| `factory` | Factory/VPS status and deployment guards |
| `forgejo` | Forgejo intake and GitOps task receipts |
| `pai-pi` | PI integration mode |
| `daemon` | Long-running mode queue/monitor |
| `fable5` | Upgraded execution stack |
| `fusion` | Multi-panel execution |
| `generate` | Media generation |
| `plinius` | Fable 5 diagnostics and upgrade tools |

---

## Command matrix

### `verify` / `attest`

- `verify <target>`: verify a target and emit an agentic attestation
  - `--out <path>`
  - `--run <id>`
  - `--scan-all`
- `attest <target>`: alias for `verify`
  - `--out <path>`
  - `--run <id>`
  - `--scan-all`

### `run`

- `run <task>`
- Options:
  - `-l, --loop <n>`: feedback loop iterations
  - `-w, --workflow <id>`: workflow definition ID
  - `-s, --skill <id>`: explicit skill override
  - `-c, --compound <n>`: compound run count

### `session`

- `session start <task>`
- `session resume <id>`
- `session list`
- `session inspect <id>`

### `skills`

- `skills list`
  - `-t, --tag <tag>`
- `skills create <name>`
  - `-s, --steps <steps>`
  - `-t, --tags <tags>`
- `skills inspect <id>`
- `skills evolve <id>`
- `skills sync`
- `skills sharpen`

### `state`

- `state`
  - `-t, --tag <tag>`
  - `--stats`

### `status`

- `status`
- Displays command availability, env bootstrap, and runtime wiring summary.

### `security`

- `security ast <file>`: summarize JS/TS structure and risky capabilities
- `security scan <target>`: hidden Unicode, reversed tags, fake wrappers, role spoofing, and instruction-smuggling markers
  - `--include-fixtures`: include intentional red-team fixtures/generators

### `cyber`

- `cyber preflight`
  - `--host <host>`
  - `--port <n>`
  - `--mode <mode>`
  - `--output <file>`
- `cyber reconcile`
  - `--preflight <file>`
  - `--capabilities <file>`
  - `--output <file>`

### `pai`

- `pai status`
- `pai telos`
  - `-s, --section <name>`
- `pai proxy <prompt>`
  - `-m, --model <id>` (default `fi-groq`)
  - `-t, --temperature <n>`
  - `-s, --system <text>`
- `pai sync`
- `pai dream`
  - `-c, --cycle <n>`
  - `--dry-run`
- `pai cert`
  - `-t, --task <text>`
  - `-l, --loop <n>`
  - `--skip-proxy-check`
- `pai bridge`
- `pai memory`
- `pai packs`
- `pai report`
- `pai run <goal>`

### `workflow`

- `workflow <file>`

### `benchmark`

- `benchmark run`
  - `-b, --benchmark <id>`
- `benchmark agents <task>`: run the same prompt against built-in or JSON-defined harnesses
  - `--with <csv>`
  - `--timeout-ms <n>`
  - `--harnesses <path>`
  - `--out <path>`
  - receipts include benchmark hygiene metadata: split, contamination risk, and local-only claim scope
- `benchmark duel <task>`: record a two-implementer eval winner
  - `--a <label>`
  - `--b <label>`
  - `--winner <a|b|tie>`
  - `--reason <text>`
  - `--reviewer <human|agent>`
  - `--out <path>`
- `benchmark duel-tally`: tally two-implementer eval receipts
  - `--dir <path>`
- `benchmark set-grade`: deterministic expected/actual set grader
  - `--expected <csv>`
  - `--actual <csv>`
  - `--threshold <n>`
- `benchmark trend`
  - `-b, --benchmark <id>`
- `benchmark list`

### `cost`

- `cost report`
  - `-h, --hours <n>`

### `exa`

- `exa search <query>`
  - `-n, --num-results <n>`
  - `-t, --type <type>`: keyword|neural|auto
  - `--include-domains <domains>`
- `exa company <name>`
- `exa sync`

### `demo`

- `demo`
  - `-q, --query <q>`

### `learned`

- `learned`
  - `-v, --verbose`

### `factory`

- `factory check`
  - `--run <id>`
- `factory capabilities`
  - `--file <path>`
  - `--run <id>`
- `factory reconcile`
  - `--output <path>`
  - `--run <id>`
- `factory rsi`
  - `--host <host>`
  - `--port <n>`
  - `--out <path>`
  - `--canary-proof <path>`
  - `--run <id>`
- `factory verify-cycle`
  - `--host <host>`
  - `--port <n>`
  - `--skill <name>`
  - `--out <path>`
  - `--allow-dirty`
  - `--canary-proof <path>`
  - `--allow-reconciled-stale-factory`
  - `--run <id>`
- `factory verify <target>`: verify a target and emit an agentic attestation
  - `--out <path>`
  - `--run <id>`
  - `--scan-all`
- `factory attest <target>`: alias for `factory verify`; emits an agentic attestation
  - `--out <path>`
  - `--run <id>`
  - `--scan-all`
- `factory deploy <command>`
  - `--token <token>`
  - `--gate-receipt <path>`
  - `--plan-receipt <path>`
  - `--url <url>`
  - `--out <path>`
  - `--yes`
  - `--run <id>`
- `factory gate <task>`
  - `--repo <path>`
  - `--host <host>`
  - `--port <n>`
  - `--capabilities <path>`
  - `--diagnostic-only`
  - `--plan-receipt <path>`
  - `--run <id>`

### `forgejo`

- `forgejo repos`
  - `--user <username>`
- `forgejo repo <repo>`
- `forgejo issues <repo>`
  - `--state <state>`
- `forgejo prs <repo>`
  - `--state <state>`
- `forgejo file <repo> <path>`
  - `--ref <ref>`
- `forgejo pr-create <repo>`
  - `--title <title>`
  - `--head <branch>`
  - `--base <branch>`
  - `--body <text>`
  - `--out <path>`
  - `--dry-run`
- `forgejo actions-coverage`
  - `--repo <repo>`
  - `--output <path>`
- `forgejo intake <ref>`
  - `--repo <repo>`
  - `--out <path>`
  - `--dry-run`
  - `--run <id>`
- `forgejo comment <ref>`
  - `--body <text>`
  - `--repo <repo>`
  - `--out <path>`
  - `--dry-run`
  - `--run <id>`
- `forgejo label <ref> <labels>`
  - `--repo <repo>`
  - `--out <path>`
  - `--dry-run`
  - `--run <id>`
- `forgejo feedbackpilot <json>`
  - `--repo <repo>`
  - `--out <path>`
  - `--dry-run`
  - `--create-issue`

### `familiar`

- `familiar capture <note>`
  - `-s, --source <src>`
- `familiar process`
- `familiar graph`
- `familiar health`
- `familiar briefing`
- `familiar loop`
  - `-p, --priority <n>`
  - `-d, --dir <path>`

### `pai-pi`

- `pai-pi status`
- `pai-pi skills`
- `pai-pi run <goal>`
  - `-l, --loop <n>`

### `daemon`

- `daemon start`
  - `-d, --detach`
- `daemon stop`
- `daemon status`
- `daemon queue <goal>`
  - `-p, --priority <n>`
  - `-t, --tags <tags>`

### `fable5`

- `fable5 status`
- `fable5 route <task>`
  - `-d, --domain <domain>`
- `fable5 models`
- `fable5 model-access`
  - `--output <path>`
  - `--run <id>`
- `fable5 flue`
- `fable5 channels`
  - `--run <id>`
- `fable5 work-inbox <text>`
  - `--surface <surface>`
  - `--user <user>`
  - `--channel <channel>`
  - `--thread <thread>`
  - `--label <labels>`
  - `--out <path>`
  - `--dry-run`
  - `--run <id>`
- `fable5 memory-b-cell <file>`
  - `--cache <path>`
- `fable5 jailbreak-assess <source>`
  - `--capability-gain <n>`
  - `--breadth <n>`
  - `--weaponization-ease <n>`
  - `--discoverability <n>`
  - `--output <path>`
- `fable5 prompt-fingerprint <file>`
  - `--output <path>`
- `fable5 skill-health`
  - `--input <path>`
  - `--skill <name>`
  - `--agent <name>`
  - `--test-command <command>`
  - `--passed <n>`
  - `--failed <n>`
  - `--evidence <text>`
  - `--source <source>`
  - `--threshold <n>`
  - `--output <path>`
- `fable5 recovery-receipt`
  - `--incident <text>`
  - `--live-signal <text>`
  - `--action-taken <text>`
  - `--decision <decision>`
  - `--stale-signal <text>`
  - `--root-cause <text>`
  - `--before <paths>`
  - `--after <paths>`
  - `--output <path>`
- `fable5 context-eval`
  - `--task <text>`
  - `--checks <json>`
  - `--output <path>`
- `fable5 sleep-time-policy`
  - `--output <path>`
- `fable5 context-repo-snapshot <root>`
  - `--output <path>`
- `fable5 opencoven-review`
  - `--output <path>`
- `fable5 opencode-review`
  - `--output <path>`
- `fable5 permission-posture`
  - `--mode <mode>`
  - `--output <path>`
- `fable5 stale-memory-quarantine`
  - `--output <path>`
- `fable5 falsification`
  - `--output <path>`
- `fable5 external-rsi-evidence`
  - `--output <path>`
- `fable5 receipt-health`
  - `--root <path>`
  - `--window-minutes <n>`
- `fable5 heartbeat`
  - `--id <id>`
  - `--name <name>`
  - `--status <status>`
  - `--task <text>`
  - `--completed <n>`
  - `--cost <n>`
  - `--run <id>`
  - `--url <url>`
  - `--secret <secret>`
  - `--out <path>`
- `fable5 verify <task>`
  - `--repo <path>`
  - `--run <id>`
  - `--trace-out <path>`
- `fable5 goal <text>`
  - `-i, --iterations <n>`
  - `-s, --min-score <n>`
- `fable5 goal-audit <objective>`
  - `--output <text>`
  - `--require <label:evidence>`
  - `--context <text>`
  - `--out <path>`
- `fable5 governance <task>`
  - `--proposer <id>`
  - `--approver <id>`
  - `--quorum <n>`
  - `--tie-break <id>`
  - `--fallback <text>`
  - `--risk <risk>`
  - `--out <path>`
- `fable5 fableflow`
  - `--out <path>`
- `fable5 spec <task>`
  - `--repo <path>`
  - `--out <file>`
- `fable5 autowiki`
  - `--repo <path>`
  - `--out <path>`
  - `--max-files <n>`
- `fable5 zte <task>`
  - `--repo <path>`
  - `--out <file>`
- `fable5 worktree <action> [name]`
- `fable5 state <project>`
  - `--add-fact <text>`
  - `--add-rule <text>`
  - `--add-failure <text>`
  - `--add-lesson <text>`
  - `--approved <text>`
  - `--rejected <text>`
  - `--performance <text>`
  - `--repo <path>`
  - `--import`
- `fable5 workflow <pattern> <task>`
  - `-s, --subtasks <list>`
  - `-n, --max-iterations <n>`
  - `-p, --panel <slug>`
  - `--category <name>`
  - `--intensity <level>`
- `fable5 compound <lesson>`
  - `--skill <name>`
- `fable5 chain <task>`
  - `--stages <list>`
  - `--worker-cmd <cmd>`
  - `--worker-args <args>`
  - `--receipt-dir <path>`
- `fable5 meta <task>`
  - `--stages <list>`
- `fable5 teams <task>`
  - `--workers <list>`
- `fable5 stack <task>`
  - `-p, --project <name>`
  - `--enable-worktrees`
  - `--enable-vision`
  - `--enable-workflows`
  - `--enable-fusion`
  - `--enable-plinius`
- `fable5 rpc`
  - `-p, --port <n>`

### `fusion`

- `fusion run <task>`
  - `-p, --panel <slug>`
  - `-j, --judge <model>`
  - `--openrouter`
- `fusion panels`

### `generate`

- `generate image <prompt>`
  - `-m, --model <id>` (default `fal-ai/nano-banana-pro`)
  - `--aspect <ratio>`
  - `-r, --reference <url>`
- `generate video <source>`
  - `-m, --model <id>` (default `alibaba/happy-horse/image-to-video`)
  - `-p, --prompt <text>`
  - `-d, --duration <n>`
  - `--720p`

### `plinius`

- `plinius godmode <task>`
  - `-p, --panel <slug>`
  - `-m, --mode <mode>`
  - `--proxy`
  - `-v, --verbose`
- `plinius ultra <task>`
  - `-o, --output <text>`
- `plinius safety <input>`
- `plinius parseltongue <input>`
  - `-c, --category <category>`
  - `-i, --intensity <level>`
- `plinius autotune <domain>`
  - `-s, --scores <list>`
- `plinius stm <text>`
  - `-m, --modules <list>`
  - `--max-length <n>`
- `plinius refusal <output>`
  - `-m, --model <id>`
  - `-t, --task <text>`
- `plinius observatory`
  - `-p, --provider <name>`
  - `-m, --model <name>`
  - `-t, --tag <tag>`
  - `-l, --limit <n>`
- `plinius liberation`
  - `--min-success <n>`
- `plinius transparency <task>`
  - `-m, --model <id>`
  - `--save`

## Env and runtime references

- Env bootstrap command: `loadEnv()`.
- Env precedence: existing process env > `.env` values.
- Files loaded from project root:
  - `.env`
  - `.env.<NODE_ENV>`
  - `.env.local`
- Proxy-sensitive commands: `pai proxy`, `pai cert`, `plinius godmode --proxy`.

## Parity checklist

Before merging command-layer changes, verify:

1. `COMMANDS.md` includes each `.command(...)` addition/removal from `src/index.ts`.
2. New or changed flags are listed in this file.
3. `CONFIG.md` includes matching bootstrap/env/proxy updates when startup behavior changes.
4. A smoke command confirms the command parses in the shell:
   - `node dist/index.js <command> --help` (or equivalent).