CLI Usage

CLI usage

🌍 English narrative is auto-generated on release. See the French version for the current full content.

WorkPilot AI ships a CLI for headless use and CI/CD integration.

Source: `docs/CLI-USAGE.md`

For headless operation, CI/CD pipelines, or terminal-only workflows, WorkPilot AI's full functionality is available without the desktop UI through the Python backend CLI.

Setup

CLI usage requires Python 3.9+ and the Claude Code CLI (pnpm install -g @anthropic-ai/claude-code). From apps/backend, create a virtual environment (uv venv && uv pip install -r requirements.txt, or the standard venv equivalent), then copy .env-files/.env.example to .env-files/.env and add an OAuth token obtained via claude setup-token.

Core Workflow

Step	Command
Create a spec	python runners/spec_runner.py --interactive or --task "..."
List specs	python run.py --list
Run a build	python run.py --spec 001
QA validation	python run.py --spec 001 --qa
Review changes	python run.py --spec 001 --review
Merge to project	python run.py --spec 001 --merge
Discard build	python run.py --spec 001 --discard

Spec creation automatically assesses complexity and assigns a tier — SIMPLE (3 phases, 1–2 files), STANDARD (6 phases, 3–10 files), or COMPLEX (8 phases, multiple services and integrations) — which determines how many pipeline phases run.

Builds and Workspaces

Every build runs in an isolated Git worktree under .worktrees/, so changes can be tested independently before merging into the main project. After QA validation completes (or is skipped with --skip-qa), the QA Reviewer and QA Fixer loop automatically until acceptance criteria pass, up to 50 iterations.

While a build is running, Ctrl+C once pauses it for added instructions, and pressing it twice exits. Alternatively, a PAUSE file dropped into the spec directory pauses after the current session, and instructions can be injected via a HUMAN_INPUT.md file.

Configuration

Key environment variables include CLAUDE_CODE_OAUTH_TOKEN (required), AUTO_BUILD_MODEL, DEFAULT_BRANCH, plus optional integration keys (LINEAR_API_KEY, GITLAB_TOKEN) and Graphiti memory settings (GRAPHITI_ENABLED, provider keys). Specs can be validated independently with python validate_spec.py --spec-dir specs/001-feature --checkpoint all.

---

➡️ Continue: Security