Canary CLI

Authenticate and onboard your repository to Canary from the terminal.

Install

npm install -g @runcanary/cli
# or run without installing:
npx @runcanary/cli login

Usage

canary login            # authenticate this device (opens your browser)
canary whoami           # show the signed-in account and your runs this month
canary logout           # revoke this device's token
canary workspace list   # list / switch your workspaces
canary setup            # verify this repo's .canary/ setup in a clean cloud sandbox
canary skills           # list what a coding agent can do with Canary (hosted index)
canary skill <name>     # print the hosted instructions for one operation

Add --json to any command for machine-readable output.

Browser login shows an animated Canary while waiting for authorization, then a contextual welcome after credentials are saved. It shows your account, active CLI workspace, locally detected GitHub repository, actual agent-skill status, and an instruction to continue in your coding agent. Press w to choose a workspace with the arrow keys and Enter, c to copy the instruction, and Enter to finish login. The instruction is simply "Onboard this repository to Canary." The CLI saves the selected workspace and sends it with setup requests.

First login starts with the workspace active on the platform. A later interactive login preserves the saved CLI workspace only after checking membership for the same account and API server. Workspace selection changes the CLI preference; repository detection does not claim a cloud connection or start onboarding.

Use canary login --no-animation or set CANARY_NO_ANIMATION=1 for plain output. Redirected output, CI, TERM=dumb, JSON, and token login also stay plain. NO_COLOR disables color.

The welcome, and the plain receipt when output is redirected, say where the local repository stands for your account: set up on Canary, connected but not set up, not connected (with the link to connect it, the server's when it sends one), or connected in a workspace you are not a member of. Login never waits on that: the redirected receipt and the welcome each give the lookup three seconds, and a repository can be connected later.

Browser login waits up to fifteen minutes for the authorization to come back — enough for a first sign-up that creates a workspace and installs the GitHub App on the way. Plain output prints a line every minute while it waits. With --json the authorization link is printed on stderr as its own JSON line whether or not a browser was opened, and stdout stays one JSON document, printed the moment the token is saved; it names the repository and the connect link when the current directory has a GitHub origin, and never waits on the repository's state (the readable receipt and the welcome show it).

Onboard a repository

canary login also installs the Canary skill for your coding agents (Claude Code, Cursor, Codex, and any agent reading the standard skill locations; skip with --no-agent-skills). The skill is a thin pointer: it teaches the agent to run canary skills and canary skill <name>, which print Canary's hosted, always-current instructions for each operation — new operations and fixes reach your agent without a CLI update. Then open your coding agent inside the repo and say:

Onboard this repository to Canary.

The agent discovers how your app installs and boots, writes the setup under .canary/, and runs canary setup — which boots it from zero in a clean cloud sandbox and registers the repo on success.

In an interactive terminal, setup shows the animated Canary, repository, saved CLI workspace, elapsed time, and the actual queued or running job state. When the verifier needs input, answer directly in the terminal and press Enter. Secret answers are masked and saved in the gitignored .canary/env.json for future runs. Escape or Ctrl+C at a question leaves it waiting; run canary setup in the same repository to resume. Ctrl+C during verification stops watching; the cloud job can keep running. A completed result stays in your terminal. Questions keep following the cloud job. If a question expires or is replaced, its unsent input is discarded and the display follows the current state.

Use canary setup --no-animation or CANARY_NO_ANIMATION=1 for plain progress. JSON, CI, redirected output or input, and TERM=dumb also stay plain. These modes return exit code 3 at a question; answer with canary setup --answer '<value>'. Exit codes remain 0 verified, 3 waiting for input, and 1 failed. NO_COLOR disables color without removing the display.

Headless / CI

canary login --token "$CANARY_TOKEN"
# or set CANARY_TOKEN in the environment and the CLI will use it directly.

Configuration

Credentials and settings live in ~/.canary/config.json (override the directory with CANARY_HOME). The stored token is written with 0600 permissions.

Canary records which canary commands ran and how they ended so the product can be understood: a random install id, a salted hash of the checkout path, the repository's root commit, the branch name, and the coding-agent session when one is running. Never file contents, briefs or finding text. canary identity prints exactly what is sent.

| Env var | Purpose | | --- | --- | | CANARY_TOKEN | Use this token directly (skips the browser flow). | | CANARY_API_URL | Override the API base URL. | | CANARY_WEB_URL | Override the authorization web URL. | | CANARY_HOME | Override the ~/.canary config directory. | | CANARY_NO_ANIMATION | Use plain login and setup output. | | NO_COLOR | Disable terminal colors. |

How canary login works

canary login runs the OAuth 2.0 Authorization Code + PKCE flow with a loopback redirect: it opens your browser to Canary (where you sign in), then exchanges a one-time code for a per-device token. The token is stored locally and sent as a bearer token on subsequent calls. Nothing but your own token is stored.

Preview the login design locally

From the monorepo, run this in a macOS or Linux terminal:

pnpm --filter @runcanary/cli preview:login

This builds and runs the real CLI against a local authorization fixture. The preview pauses at the welcome so you can try w, the arrow keys, and c. Press Enter to finish a cycle; it then replays automatically. Press Ctrl+C during the animation to exit, or add --once to stop after one completed cycle. It uses a temporary CANARY_HOME, a simulated account, and a local substitute for the browser launcher. Your saved account and agent skills are untouched. The preview fixture is excluded from the published package.

Preview the setup design locally

From the monorepo, run this in an interactive terminal:

pnpm --filter @runcanary/cli preview:setup

This builds and runs the real canary setup command against a local HTTP fixture using a temporary acme/web repository and sample workspace. It shows the queue, verification, an inline question, and a completed result. Enter alex when asked. The preview ends after one cycle and leaves the result visible.

| Command | Preview | | --- | --- | | pnpm --filter @runcanary/cli preview:setup --secret | Masked sample password; enter preview-only. | | pnpm --filter @runcanary/cli preview:setup --failure | Failed verification and its recovery instructions. | | pnpm --filter @runcanary/cli preview:setup --loop | Repeat after each completed cycle; Ctrl+C exits. |

The fixture uses a temporary CANARY_HOME, blocks external fetches, skips agent skill installation, and removes its temporary files on exit. It does not start your app, upload your repository, or change your saved account. The fixture is excluded from the published package.

For real onboarding, run canary setup from the application repository whose .canary/ recipe your coding agent prepared. That command uses your saved account and starts or resumes cloud verification.