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

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
security	Security scanners
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
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.

security

• security scan <target>: hidden Unicode, reversed tags, fake wrappers, role spoofing, and instruction-smuggling markers
  • --include-fixtures: include intentional red-team fixtures/generators

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

factory

• factory check
• factory capabilities
  • --file <path>
• factory gate <task>
  • --repo <path>
  • --diagnostic-only

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 verify <task>
  • --repo <path>
• fable5 goal <text>
  • -i, --iterations <n>
  • -s, --min-score <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>
  • --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).