CLI Reference - PairCoder Docs

Quick Task Index

Task	Command
Getting Started
Initialize a project	`bpsai-pair init .`
Check project status	`bpsai-pair status`
Validate setup	`bpsai-pair validate`
Planning
Create a new plan	`bpsai-pair plan new my-feature --type feature`
List all plans	`bpsai-pair plan list`
See plan progress	`bpsai-pair plan status`
Tasks
List all tasks	`bpsai-pair task list`
Get next task	`bpsai-pair task next`
Start a task	`bpsai-pair task update TASK-001 --status in_progress`
Complete a task	`bpsai-pair task update TASK-001 --status done`
Trello
Connect to Trello	`bpsai-pair trello connect`
Start Trello task	`bpsai-pair ttask start CARD-ID`
Complete Trello task	`bpsai-pair ttask done CARD-ID --summary "..."`
Support
Create a support ticket	`bpsai-pair support create --type bug --title "..."`
List your tickets	`bpsai-pair support list`
View ticket details	`bpsai-pair support show <id>`
Open support portal	`bpsai-pair support open`
Quality Control
Initialize QC structure	`bpsai-pair qc init`
List test suites	`bpsai-pair qc list`
Validate suite specs	`bpsai-pair qc validate`
View latest results	`bpsai-pair qc report`
Engage
Run a sprint autonomously	`bpsai-pair engage backlog.md --sprint 1`
Review
Review a GitHub PR	`bpsai-pair review pr 123`
Review current branch	`bpsai-pair review branch`
Project Management
Start a work item	`bpsai-pair pm start CARD-ID`
Complete a work item	`bpsai-pair pm done CARD-ID --summary "..."`
View item hierarchy	`bpsai-pair pm tree CARD-ID`
Query
Query metrics	`bpsai-pair query metrics success_rate`
Query tasks	`bpsai-pair query tasks --status in_progress`
Sweep
Find dead code after changes	`bpsai-pair sweep`
Sweep with auto-fix	`bpsai-pair sweep --fix`
Sweep against specific ref	`bpsai-pair sweep --since v2.23.0`
Health & Fleet
Run health check	`bpsai-pair doctor`
Check fleet versions	`bpsai-pair fleet check`
Security
Scan for secrets	`bpsai-pair security scan-secrets`
Enter contained mode	`bpsai-pair contained-auto`

Command Groups

Group	Purpose	Count
Core	init, feature, pack, status, validate, ci, context-sync, contained-auto, scan-secrets, scan-deps, upgrade, wizard, subagent, migrate, setup, engage, doctor, sweep	16
Plan	Plan creation, listing, status, estimation, sync	8
Task	Local task file management and archival	12
Skills	Skill validation, listing, export, scoring	8
Gaps	Skill gap detection and analysis	4
Orchestrate	Multi-agent orchestration, handoff, auto-run	7
Metrics	Token/cost tracking, velocity, burndown, accuracy	9
Budget	Budget checking, estimation, status	3
Timer	Session timing and tracking	5
Benchmark	Performance benchmarking	4
Security	Secret scanning, dependency scanning, hooks	4
Containment	Contained autonomy management	3
Trello	Board configuration, fields, webhooks	18
ttask	Trello card lifecycle (start, done, block, check)	9
GitHub	PR creation, merging, linking, archival	8
MCP	MCP server for Claude Desktop	3
QC	Browser-driven regression testing: init, list, validate, report	4
Arch	Architecture enforcement and split suggestions	2
License	License install, activate, machine binding, verify	10
Subscription	Subscription management (Stripe Billing Portal)	2
Support	Support tickets (create, list, show, open)	4
Config	Configuration show, update, validate	6
Preset	Project preset management	3
State	Task state machine management	6
Enforce	Enforcement gates	2
Session	Session detection and context recovery	3
Compaction	Context compaction and recovery	5
Feedback	Estimation feedback and calibration	4
Telemetry	Telemetry configuration and export	4
Workspace	Multi-project workspace management	6
Intent	Intent detection and flow suggestion	3
Sprint	Sprint completion and listing	2
Release	Release preparation and checklists	3
Standup	Standup generation and posting	2
Template	Template checking and listing	2
Cache	Cache management (stats, clear, invalidate)	3
Audit	Bypass audit log (summary, list, clear)	3
Migrate	Project migration	1
Subagent	Subagent gap detection	1
Review	Code review: PR, task, branch, auto-route	4
Fleet	Version compliance across workspace repos	1
Query	Query metrics, state, tasks, task-state, skill, qc-trends	6
PM	Project management: start, done, block, sync, status, children, tree, diagnostics, config, create, move, comment, check, set-field, link, unlink, action, sprint	20
Total		233

Core Commands

bash

# Initialize new project
bpsai-pair init my-project --preset bps

# Create feature branch
bpsai-pair feature add-auth --type feature

# Package context for AI agents
bpsai-pair pack --lite --out context.tgz

# Check status
bpsai-pair status

# Start contained autonomous session
bpsai-pair contained-auto

# Run holistic health check
bpsai-pair doctor
bpsai-pair doctor --fix    # Auto-fix fixable issues
bpsai-pair doctor --json   # JSON output

Engage Command

Parse a backlog and autonomously execute the sprint. See the Engage guide for full usage.

bash

# Execute a sprint from a backlog file
bpsai-pair engage backlog-sprint-28.md --sprint 28

# Dry-run: show plan without executing
bpsai-pair engage backlog.md --dry-run

# Control parallelism
bpsai-pair engage backlog.md --max-parallel 5

# Skip the Navigator planning phase
bpsai-pair engage backlog.md --skip-planning

# JSON output
bpsai-pair engage backlog.md --json

Review Commands

Code review commands for PRs, tasks, and branches. See the Review guide for full usage.

bash

# Review a GitHub PR by number
bpsai-pair review pr 146
bpsai-pair review pr 146 --post   # Post review to PR via gh
bpsai-pair review pr 146 --json   # Structured JSON output

# Review a task's changes
bpsai-pair review task T18.3
bpsai-pair review task             # Review uncommitted changes

# Review the current branch diff against base
bpsai-pair review branch
bpsai-pair review branch --base main

# Auto-route: detect PR number, task ID, or default to branch
bpsai-pair review auto 146         # Routes to review pr
bpsai-pair review auto T18.3       # Routes to review task
bpsai-pair review auto             # Routes to review branch

Planning Commands

bash

# Create feature plan
bpsai-pair plan new my-feature --type feature --title "My Feature"

# Show plan with progress
bpsai-pair plan status plan-2025-12-my-feature

# Sync to Trello
bpsai-pair plan sync-trello plan-2025-12-my-feature --dry-run

Task Commands

bash

# Get and start next task
bpsai-pair task next --start

# Update task status
bpsai-pair task update TASK-001 --status in_progress
bpsai-pair task update TASK-001 --status done

# Archive completed tasks
bpsai-pair task archive --completed

Skills Commands

bash

# List and validate
bpsai-pair skill list
bpsai-pair skill validate

# Export to other platforms
bpsai-pair skill export --all --format cursor
bpsai-pair skill export my-skill --format windsurf

Trello Commands (ttask)

bash

# List and show
bpsai-pair ttask list
bpsai-pair ttask show TRELLO-abc123

# Lifecycle
bpsai-pair ttask start TRELLO-abc123
bpsai-pair ttask done TRELLO-abc123 --summary "Implemented feature"
bpsai-pair ttask block TRELLO-abc123 --reason "Waiting for API"

# Comments
bpsai-pair ttask comment TRELLO-abc123 "50% complete"

Metrics Commands

bash

bpsai-pair metrics summary
bpsai-pair metrics breakdown --by model
bpsai-pair metrics export --format csv --output metrics.csv
bpsai-pair budget status

Security Commands

bash

bpsai-pair security scan-secrets --staged
bpsai-pair security scan-deps
bpsai-pair security install-hook
bpsai-pair contained-auto
bpsai-pair containment status
bpsai-pair containment rollback

QC Commands

Interactive browser regression testing powered by Claude in Chrome. Requires the Claude in Chrome extension (Chrome only).

For setup and full usage, see the QC Agent guide.

bash

# Scaffold QC directory structure with example suite and config
# Non-destructive: won't overwrite existing files
bpsai-pair qc init

# Discover all .qa.yaml suites in .paircoder/qc/suites/
bpsai-pair qc list
bpsai-pair qc list --tags smoke,regression   # Filter by tag
bpsai-pair qc list --json                    # Machine-readable output

# Validate YAML syntax and required fields for all suites
# Unresolved ${VAR} variables are allowed at validation time
bpsai-pair qc validate
bpsai-pair qc validate --json

# Display summary of latest QC run from .paircoder/qc/reports/
bpsai-pair qc report
bpsai-pair qc report --json

Deprecated aliases: bpsai-pair qa init|list|validate|report still works but prints a deprecation warning to stderr. Use bpsai-pair qc instead.

Architecture Commands

bash

# Check specific files
bpsai-pair arch check src/services/task.py

# Get split suggestions
bpsai-pair arch suggest-split src/large_module.py

Query Commands

Query project state, metrics, and tasks from the command line.

bash

# Query metrics
bpsai-pair query metrics success_rate
bpsai-pair query metrics estimation_accuracy --days 30
bpsai-pair query metrics agent_performance --task-type feature --json

# Query project state
bpsai-pair query state active-tasks
bpsai-pair query state current-plan --json

# Query tasks with filters
bpsai-pair query tasks --status in_progress
bpsai-pair query tasks --json

# Query task state transitions
bpsai-pair query task-state <task-id>

# Execute a query skill
bpsai-pair query skill <skill-name>

# Query QC historical trends and flaky scenarios
bpsai-pair query qc-trends

PM Commands

Unified project management operations. Works with any configured PM provider (Trello, etc.).

bash

# Lifecycle
bpsai-pair pm start CARD-ID          # Move to in_progress
bpsai-pair pm done CARD-ID --summary "Implemented feature"
bpsai-pair pm block CARD-ID --reason "Waiting for API"
bpsai-pair pm move CARD-ID --status review

# Information
bpsai-pair pm status                 # PM provider connection status
bpsai-pair pm children CARD-ID       # List children of a work item
bpsai-pair pm tree CARD-ID           # Display hierarchy tree
bpsai-pair pm diagnostics            # Run PM provider diagnostics
bpsai-pair pm config                 # Show resolved PM workflow configuration

# CRUD operations
bpsai-pair pm create --title "New item" --type task
bpsai-pair pm comment CARD-ID "Progress update"
bpsai-pair pm check CARD-ID --item "Acceptance criterion 1"
bpsai-pair pm set-field CARD-ID --field complexity --value 40

# Linking
bpsai-pair pm link PARENT-ID CHILD-ID [CHILD-ID...]
bpsai-pair pm unlink CHILD-ID

# Actions and sync
bpsai-pair pm action approve CARD-ID
bpsai-pair pm sync                   # Sync local tasks to PM provider

# Sprint lifecycle
bpsai-pair pm sprint start PLAN-ID
bpsai-pair pm sprint complete PLAN-ID

Fleet Commands

Check bpsai-pair version compliance across all repos in a workspace.

bash

# Check version compliance across workspace repos
bpsai-pair fleet check
bpsai-pair fleet check --upgrade    # Upgrade stale venvs
bpsai-pair fleet check --json       # JSON output

License Commands

bash

# Install and check license
bpsai-pair license install ~/Downloads/license.json
bpsai-pair license status

# Machine binding (v2.11+)
bpsai-pair license machine-id        # View machine identifier
bpsai-pair license machine-id --full # Full machine details
bpsai-pair license activate          # Activate this machine
bpsai-pair license activate --name "Work Laptop"
bpsai-pair license deactivate        # Free up machine slot
bpsai-pair license machines          # List activated machines
bpsai-pair license machines --json   # JSON output

# Validation troubleshooting
bpsai-pair license clear-cache       # Clear validation cache
bpsai-pair license verify-keypair    # Verify CLI/API key alignment

Subscription Commands

bash

# Check subscription status
bpsai-pair subscription status
bpsai-pair subscription status --json

# Manage subscription (opens Stripe Billing Portal)
bpsai-pair subscription manage           # Opens in browser
bpsai-pair subscription manage --no-browser  # Just print URL

Support Commands

bash

# Create a support ticket
bpsai-pair support create --type bug --title "Issue title" --description "Details"

# List your tickets
bpsai-pair support list
bpsai-pair support list --status open

# View ticket details
bpsai-pair support show <ticket-id>

# Open support portal in browser
bpsai-pair support open

Ticket types: bug, feature, question, billing, general. See the Support guide for details.

Environment Variables

Variable	Purpose
`TRELLO_API_KEY`	Trello API key
`TRELLO_TOKEN`	Trello OAuth token
`GITHUB_TOKEN`	GitHub personal access token
`PAIRCODER_CONFIG`	Override config file path
`PAIRCODER_OFFLINE`	Enable offline mode (skip online validation)