Canary CLI (canary-cli)

canary-cli is the command-line interface for Canary: it registers a project, builds a dependency inventory from your lockfiles, and triggers vulnerability scans against that inventory.

Install

Global install (recommended):

npm install -g canary-cli
canary --help

One-off run without installing globally:

npx --package canary-cli canary --help

Quick Start

From the root of your repo:

canary init
canary scan

canary init will:

• Authenticate via GitHub Device Flow
• Register (or link) a Canary project
• Write a local .canary config file
• Optionally generate a GitHub Actions workflow and set secrets
• Build and upload an initial dependency inventory

Commands

canary init

Registers a new project (or links to an existing one) and optionally sets up GitHub Actions.

canary init

canary inventory

Builds inventory from supported lockfiles. Can print a summary, output JSON, write to a file, or send to Canary.

canary inventory
canary inventory --json
canary inventory --output inventory.json
canary inventory --send
canary inventory --no-dev

canary scan

Updates inventory (if possible), triggers a scan, and prints vulnerabilities.

canary scan
canary scan --severity critical,high
canary scan --ecosystem npm
canary scan --json

canary status

Shows local project config and the last scan summary (if you have a valid session).

canary status

If you run canary with no command, it defaults to status.

Supported Lockfiles

Inventory currently supports:

• npm: package-lock.json, yarn.lock
• Python: requirements.txt, Pipfile.lock, poetry.lock
• Go: go.mod, go.sum
• Ruby: Gemfile.lock
• Rust: Cargo.lock
• Composer: composer.lock
• NuGet: packages.lock.json
• Maven: pom.xml

Configuration & Storage

• Project config is stored in a .canary file in your repo (created by canary init).
• Session credentials are stored at ~/.config/canary/credentials.json.
• Project API keys are stored at ~/.config/canary/api-keys.json.

CI (GitHub Actions)

canary init can generate .github/workflows/canary-scan.yml. The workflow installs canary-cli and runs:

canary inventory --send

It expects GitHub secrets:

• CANARY_INGEST_TOKEN (inventory ingest API key)
• CANARY_WORKER_URL (Canary Worker base URL)

Environment Variables

• CANARY_API_URL - Override the Canary Worker URL (alternative to --api-url)
• CANARY_INGEST_TOKEN - API key for inventory ingestion (CI / non-interactive use)
• CANARY_DASHBOARD_URL - Override the dashboard base URL used in links