Commands
This is the exact-command reference, not the best first learning path. If you are deciding what to do, start with Choose your workflow or a tutorial. Return here when you know your goal and need an option, argument, or machine-readable contract.
For almost every project, the basic story is: create/import a project → pull if Excel is newer → edit src/ → lint/analyze → push → run or test → inspect the result. The source, workbook, and session model explains why these are separate commands.
xlflow exposes a Cobra-based CLI. Every command accepts the global --json flag for machine-readable output. Retryable workbook commands also accept --wait and --wait-timeout <duration>; waiting is opt-in and defaults to a 30-second limit. A workbook recovery quarantine is different from lock contention: --wait does not bypass it, and an explicit recovery command is required.
xlflow [command] --json
xlflow [command] --wait --wait-timeout 45sUse command pages for workflow guidance and the canonical CLI contract in JSON Output.
| Command | Purpose |
|---|---|
| new | Create a new xlflow project and macro-enabled workbook or add-in. |
| init | Initialize an xlflow project from an existing workbook or add-in. |
| capabilities | Show machine-readable command safety metadata. |
| rules | List canonical static-analysis rule metadata without opening Excel. |
| doctor | Diagnose Excel, COM, PowerShell, VBIDE access, and source GUI boundaries. |
| attach | Validate that the active Excel workbook matches the configured workbook. |
| backup | List rollback-capable workbook backups for the configured workbook. |
| list | List workbook resources. The public subcommand is list forms. |
| form | Manage UserForms through source scaffolds, snapshot, build, and image export. |
| formulas | Extract worksheet formulas into region-based JSONL snapshots without Excel. |
| pull | Export workbook VBA components into configured source directories. |
| push | Import edited source files back into the configured workbook. |
| build | Build a validated Excel-backed release workbook without changing the development workbook. |
| pack | Build a release .xlsm artifact from source and a workbook template. |
| rollback | Restore the configured workbook from an xlflow-managed backup. |
| status | Show project, source, workbook, and session state in one read-only command. |
| session | Keep Excel and the configured workbook open across repeated commands. |
| save | Save the workbook held by the managed xlflow session. |
| recovery | Verify and clear workbook recovery-required state. |
| runner | Manage the persistent xlflow runner marker module. |
| run | Run a workbook macro from the CLI. |
| export-image | Export a worksheet range as a PNG image through Excel COM. |
| edit | Mutate a live session workbook for setup and visual tuning. |
| macros | Discover runnable public workbook macro entrypoints without executing user code. |
| ui | Manage xlflow-owned worksheet buttons. |
| test | Discover and run workbook VBA test procedures. |
| type db | Manage generated TypeLib databases for LSP type intelligence. |
| diff | Compare workbook files and optionally exported VBA source trees. |
| inspect | Inspect saved workbook state or UserForm state. |
| impact | Show the confirmed VBA caller/callee blast radius for one procedure. |
| graph dependencies | Show confirmed procedure, module, and project-type dependency projections. |
| inspect-gui | Scan source for automation-hostile GUI boundaries without opening Excel. |
| lint | Lint VBA source files for agent-hostile and compile-dialog-prone patterns. |
| lsp | Start the reusable VBA language server for editor integrations. |
| fmt | Format VBA source files with a conservative, non-destructive formatter. |
| analyze | Analyze VBA source for runtime-risk patterns without Excel COM. |
| metrics | Calculate procedure metrics and architectural hotspot rankings without Excel COM. |
| check | Run lint, analyze, and doctor as a combined preflight. |
| module | Create module source files and install bundled xlflow helper modules. |
| completion | Generate shell completion scripts through Cobra. |
| process | List and manage local Excel processes. |
| skill | Install the bundled xlflow skill for AI agent tools. |
| version | Show xlflow build metadata. |
| update | Check whether a newer xlflow release is available. |