Skip to content

Getting Started

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/cli
canopy --help

Update 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.

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 login
canopy whoami

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.

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-app
canopy 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.

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> --follow
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.

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.

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" }
]
}
JSON
canopy setups create --file setup.json --wait

canopy 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.

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.