# Canary CLI

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

## Install

Requires Node.js 20 or newer. Bun is also supported for running the CLI.

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

> **Rebranding note:** the same CLI is also published as
> [`@runcofactor/cli`](https://www.npmjs.com/package/@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:

```bash
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`:

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

## Run Tests

### Local Playwright tests

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

All standard Playwright options are passed through.

### Remote workflow tests

```bash
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

```bash
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

```bash
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:

```bash
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**.

```bash
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:

```bash
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` |