CLI reference
CLI
paxfx command reference for the @pax-sh/cli executable. Generated from source to prevent drift.
paxfx is the Pax command-line interface from @pax-sh/cli. Every command runs locally and supports --json for stable machine-readable output.
Install
pnpm
pnpm install
pnpm build
pnpm paxfx --helpConcept first
Commands group into three families:
- Production loop —
understand,direct,design,motion,lottie,film,critic,repair,ship - Lifecycle —
init,doctor,update,migrate,uninstall - Registry and agents —
blocks,effects,protocol,mcp,integrations
Legacy aliases (scan, check, create, recipes) still work with deprecation warnings. Prefer the loop namespace for new scripts.
Global flags
| Flag | Purpose |
|---|---|
--json | Stable machine-readable JSON on stdout |
--verbose | Verbose diagnostics on stderr |
--quiet | Suppress non-essential stdout |
--no-color | Disable ANSI color |
--ci | Non-interactive CI mode |
--dry-run | Preview mutations without writing |
--yes | Confirm destructive actions |
--force | Overwrite existing targets |
--cwd <path> | Working directory |
Generated command reference
Auto-generated from paxfx --help --json (CLI v1.0.0). Run pnpm docs:generate after command changes.
Global flags
| Flag | Purpose |
|---|---|
--json | See paxfx --help |
--verbose | See paxfx --help |
--quiet | See paxfx --help |
--no-color | See paxfx --help |
--ci | See paxfx --help |
--dry-run | See paxfx --help |
--yes | See paxfx --help |
--force | See paxfx --help |
--cwd | See paxfx --help |
--help | See paxfx --help |
--version | See paxfx --help |
Production loop commands
understanddirectdesignmotionlottiefilmcriticrepairship
Production loop
| Command | Summary | JSON | Mutating | Network |
|---|---|---|---|---|
paxfx critic | Run deterministic or rendered visual QA checks | yes | no | no |
paxfx design add | Install a registry block or component into the host app | yes | yes | no |
paxfx design export | Export design plan, install script, or token sheet | yes | yes | no |
paxfx design init | Scaffold .pax/design.json from locked direction | yes | yes | no |
paxfx design inspect | Human-readable design plan report | yes | no | no |
paxfx design list | List registry design assets | yes | no | no |
paxfx design match | Match registry assets to semantic roles without writing files | yes | no | no |
paxfx design plan | Generate design plan from direction, brand, and registry matching | yes | yes | no |
paxfx design tokens | Emit resolved CSS token bindings for the host stack | yes | no | no |
paxfx design validate | Validate design plan against schema, direction, and brand | yes | no | no |
paxfx direct approve | Approve a proposed direction and write approval diff | yes | yes | no |
paxfx direct export | Export downstream pillar constraints (design, motion, lottie, film) | yes | yes | no |
paxfx direct generate | Generate distinct creative directions from brief and brand | yes | yes | no |
paxfx direct init | Create a non-interactive creative brief template | yes | yes | no |
paxfx direct inspect | Inspect creative direction and agent context | yes | no | no |
paxfx direct lock | Lock direction fields for downstream change control | yes | yes | no |
paxfx direct reject | Reject a direction and append to rejection log | yes | yes | no |
paxfx direct revise | Create a versioned revision of the active direction | yes | yes | no |
paxfx direct validate | Validate direction against schema and brand model | yes | no | no |
paxfx film demo | Render deterministic demo or launch video | yes | yes | no |
paxfx film export | Export scene or demo to media or compile targets | yes | yes | no |
paxfx lottie validate | Validate Lottie JSON | yes | no | no |
paxfx motion export | Export motion report, timeline snapshots, lottie, or film segments | yes | yes | no |
paxfx motion init | Initialize motion plan from locked direction | yes | yes | no |
paxfx motion inspect | Inspect motion plan: ownership, timing, conflicts, budget | yes | no | no |
paxfx motion plan | Build or refresh motion plan with semantic roles and timelines | yes | yes | no |
paxfx motion profile | Inspect scanned .pax/motion.json profile | yes | no | no |
paxfx motion validate | Validate motion plan against roles, budget, and reduced-motion policy | yes | no | no |
paxfx repair | Apply safe repairs from the latest check report | yes | yes | no |
paxfx ship add | Install registry assets into the host repository | yes | yes | no |
paxfx ship export | Export artifacts ready for host app integration | yes | yes | no |
paxfx understand brand | Ingest, inspect, and version the brand intelligence document | yes | yes | no |
paxfx understand scan | Scan repository for brand and motion signals | yes | yes | no |
Lifecycle
| Command | Summary | JSON | Mutating | Network |
|---|---|---|---|---|
paxfx doctor | Diagnose toolchain, config, cache, and provider mode | yes | no | no |
paxfx init | Create .pax/ project files and manifest without clobbering existing content | yes | yes | no |
paxfx migrate project | Migrate pax.project.json to the current schema version | yes | yes | no |
paxfx migrate scene | Migrate a scene document to the current schema version | yes | yes | no |
paxfx uninstall integrations | Remove Pax editor integrations | yes | yes | no |
paxfx uninstall pax | Remove .pax/ project state (requires --yes) | yes | yes | no |
paxfx update config | Merge missing defaults into project config | yes | yes | no |
paxfx update project | Refresh project manifest provenance and schema metadata | yes | yes | no |
Registry
| Command | Summary | JSON | Mutating | Network |
|---|---|---|---|---|
paxfx add | Install blocks/<id> into the host repository | yes | yes | no |
Agent integrations
| Command | Summary | JSON | Mutating | Network |
|---|---|---|---|---|
paxfx protocol generate | Regenerate agent adapters from canonical protocol | yes | yes | no |
paxfx protocol info | Show creative-engineering protocol version and stages | yes | no | no |
paxfx protocol install | Merge generated protocol instructions into agent host files | yes | yes | no |
paxfx protocol parity | Verify generated adapters match canonical protocol hash | yes | no | no |
paxfx protocol validate | Validate canonical protocol structure | yes | no | no |
Deprecated aliases
| Prefer | Legacy alias |
|---|---|
paxfx understand scan | understand scan |
paxfx understand brand | understand brand |
paxfx design list | design list |
paxfx design add | design add |
paxfx film export | film export |
paxfx film demo | film demo |
paxfx critic | critic |
paxfx add | design add or ship add |
paxfx migrate scene | migrate scene |
paxfx uninstall integrations | uninstall integrations |
Schemas
JSON schemas shipped with Pax. Source: docs/architecture/schemas/.
| Schema | Purpose |
|---|---|
pax-brand.v1.json | Pax Brand Intelligence Document |
pax-brief.v1.json | Pax Creative Brief |
pax-check-report.v1.json | Pax Check Report |
pax-check-report.v2.json | Pax Check Report |
pax-creative-protocol.v1.json | Pax Creative-Engineering Protocol |
pax-design-plan.v1.json | Pax Design Plan |
pax-direction.v1.json | Pax Creative Direction |
pax-motion-plan.v1.json | Pax Motion Plan |
pax-output-manifest.v1.json | Pax Output Manifest |
pax-project.v1.json | Pax Project Manifest |
pax-protocol-run.v1.json | Pax Protocol Run Checkpoint |
pax-scene.v1.json | Pax Scene |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Usage error |
| 2 | Unknown command |
| 3 | Configuration / check failure |
| 4 | IO error |
| 5 | Process failure |
| 130 | Cancelled |
Related
Was this page helpful?
Answers are not recorded or transmitted. Pax has no telemetry.