508 lines
12 KiB
Markdown
508 lines
12 KiB
Markdown
# 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 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 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).
|
|
|