Getting Started

Install the CLI

The canopy CLI is Bun-managed and lives at host/cli/ in the monorepo. Until it’s published as a standalone package, run it from a checkout:

cd host/cli
bun install
bun run src/main.ts login

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

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-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) or --parent <environment_id> (create this as a service under an existing environment - see Environments & Services).

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

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

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.