fable-agent/COMMANDS.md

# Command Reference

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

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 |
| `session` | Session lifecycle |
| `skills` | Skill registry ops |
| `state` | Knowledge state / stats view |
| `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 |
| `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

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

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

### `familiar`

- `familiar capture <note>`
  - `-s, --source <src>`
- `familiar process`
- `familiar graph`
- `familiar health`
- `familiar briefing`

### `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 verify <task>`
- `fable5 goal <text>`
  - `-i, --iterations <n>`
  - `-s, --min-score <n>`
- `fable5 worktree <action> [name]`
- `fable5 state <project>`
  - `--add-fact <text>`
  - `--add-rule <text>`
  - `--add-failure <text>`
  - `--add-lesson <text>`
  - `--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>`
- `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 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).