Getting Started
Install the CLI
Section titled “Install the CLI”The canopy CLI is published on Canopy’s own package registry, which needs no account to install from. It needs
Node.js 22 or newer. Point the @canopy scope at the registry once, then install:
npm config set @canopy:registry https://api.canopy.pm/registry/npm/npm install -g @canopy/clicanopy --helpUpdate it with npm update -g @canopy/cli. The CLI is free to use with Canopy; it is not open source (see the LICENSE
in the package). Bun users can put the same @canopy:registry=... line in ~/.npmrc and run bun add -g @canopy/cli.
Log in
Section titled “Log in”canopy login is OAuth-style: it opens a browser to the Canopy dashboard,
which redirects back to a local callback server the CLI starts, landing
an API key in your local config. Use --manual if a browser can’t reach
your machine (it accepts a pasted JSON payload instead).
canopy logincanopy whoamiOr start in the dashboard
Section titled “Or start in the dashboard”At app.canopy.pm choose New project, connect your Git provider, pick a repository (its default branch is already chosen) and Canopy reads it: the services it finds, how each is built, the ports, the databases and caches it suggests, and why each was proposed. You review that, change what is wrong, enter any value the repository cannot carry, and press Deploy. Canopy then creates the project, the environment, its services and the first deploy as one operation and shows each step as it finishes; if one fails it says which and why, and Try again continues from there without repeating what is done. The dashboard guide walks through every step.
Create a project and environment
Section titled “Create a project and environment”A project groups environments together (e.g. one project per app). An environment is a deployable unit - its own build, domains, database, and variables.
canopy projects create my-appcanopy environments create main --project my-app --repository your-org/your-repo--repository is required unless you pass --template <template_id>
(deploy from a reusable template instead). To add a service to an
existing environment, use canopy app-services create --env <id> --name <service-name>; see Environments & Services. The CLI
does not accept --parent on environments create.
Deploy
Section titled “Deploy”A push to the linked branch triggers a deploy automatically via webhook. To trigger one manually:
canopy deploys create --env <environment_id>canopy deploys list --env <environment_id>canopy deploys logs <build_id> --followAdd a domain
Section titled “Add a domain”canopy domains add myapp.example.com --env <environment_id>TLS is provisioned automatically once the domain’s DNS resolves to the host - see Deploys & the Staged Pipeline for what happens under the hood.
Set environment variables
Section titled “Set environment variables”canopy variables set NEXT_PUBLIC_API_URL https://api.example.com --env <environment_id>canopy variables list --env <environment_id>variables set is a real upsert - setting an already-existing name
updates it in place, it won’t error on a duplicate.
Set up a whole project in one request
Section titled “Set up a whole project in one request”The dashboard flow is one durable request, and you can send it yourself. This creates a project, an environment from a repository and its first deploy, and survives a restart of Canopy while it runs:
cat > setup.json <<'JSON'{ "project": { "name": "my-app" }, "environments": [ { "name": "production", "repository": "your-org/your-repo", "branch": "main" } ]}JSONcanopy setups create --file setup.json --waitcanopy setups show <setup_id> lists its steps; a failed setup resumes with canopy setups retry <setup_id>. The
request can also carry services, secret values, secondary repositories, a Blueprint and a domain per environment, see
Environments & Services.
Change what a push runs
Section titled “Change what a push runs”A repository can describe its own build and deploy in a canopy.pipeline.ts. You can write one in the dashboard, step
by step, and save it to the repository: see Canopy Pipelines.