Canary CLI

Run tests, query issues, and manage AI agent skill templates from the command line.

Install

npm install -g @canaryai/cli
# or
bun add -g @canaryai/cli

Rebranding note: the same CLI is also published as @runcofactor/cli, which installs the cofactor binary instead of canary. Both packages ship the identical build at the same version — install whichever brand you prefer, and substitute cofactor for canary in the commands below if you installed @runcofactor/cli.

Login

Authenticate with your Canary account before using the CLI:

canary login

Options:

• --org <name> - Select organization by name or ID (for multi-org users)
• --app-url <url> - Custom app URL (e.g. http://localhost:5173 for local dev)
• --api-url <url> - Custom API URL (e.g. http://localhost:3000 for local dev)
• --no-open - Don't auto-open browser

To switch environments, set CANARY_API_URL:

export CANARY_API_URL=http://localhost:3000
canary login --app-url http://localhost:5173

Run Tests

Local Playwright tests

canary test
canary test --grep "login" --headed --workers 1

All standard Playwright options are passed through.

Remote workflow tests

canary test --remote
canary test --remote --tag smoke
canary test --remote --property "My App" --environment staging

Options:

• --token <key> - API key (or set CANARY_API_TOKEN)
• --api-url <url> - API URL (default: https://api.runcofactor.com)
• --property <name|id> - Target a specific property
• --environment <name|id> - Target a specific environment
• --tag <tag> - Filter workflows by tag
• --name-pattern <pat> - Filter workflows by name pattern
• --verbose, -v - Show all events

Issues

Search and inspect QA issues detected by Canary.

List issues

canary issues list
canary issues list --severity high --status open
canary issues list --search "timeout" --format markdown

Options:

• --search <query> - Full-text search
• --severity <level> - Filter: low, medium, high, unknown
• --status <statuses> - Filter: open, closed, not_a_bug (comma-separated)
• --property-id <uuid> - Filter by property
• --page <n> - Page number (default: 1)
• --page-size <n> - Page size (default: 25)
• --json - Output raw JSON
• --format markdown - Output as markdown

Get issue details

canary issues get <issue-id>
canary issues get <issue-id> --format markdown

AI Agent Skill Templates

Output or install reusable skill templates that teach AI agents (Claude Code, Codex, Copilot, etc.) how to use the Canary CLI:

canary skill help                    # list available templates
canary skill issue-log-xref          # output a template to stdout
canary skill install issue-log-xref  # auto-detect agent and install it
canary skill install issue-log-xref --agent codex  # install to .codex/skills/

Prompt Library

Curated, agent-agnostic starter prompts — common recipes for getting going with a coding agent. The library mixes Cofactor's global prompts with your org's own prompts, and is also browsable in the web app under Agent Tools → Prompt Library.

canary prompts list                                  # global + your org prompts
canary prompts get install-cli                       # print a prompt's markdown to stdout
canary prompts get install-cli --json
canary prompts create recipe.md --title "Set up CI"  # share a prompt with your org
cat recipe.md | canary prompts create --stdin --title "Set up CI"
canary prompts delete <id>

canary prompts get <slug> prints raw markdown so you can pipe or paste it straight into an agent. --global (superadmin only) creates a Cofactor-wide prompt instead of an org one.

Release QA (CI/CD)

Trigger and monitor Release QA runs from CI pipelines:

canary release trigger --property-id <uuid>
canary release status <run-id>
canary release run --property-id <uuid> --timeout 600

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | CANARY_API_URL | https://api.runcofactor.com | API endpoint | | CANARY_APP_URL | https://app.runcofactor.com | App URL for login | | CANARY_API_TOKEN | — | API key (alternative to canary login) | | CANARY_LOCAL_PORT | — | Default port for canary run / canary tunnel |