CLI Reference

This is a snapshot of canopy --help’s own output, organized by area. If it drifts, the CLI itself is the source of truth - run canopy --help or check host/cli/src/main.ts.

Global flags on any command: --json (machine-readable output), --profile <name> (switch config profile for this call). login also accepts --manual, --api-key, --api-url, --app-url, --payload.

Some command groups below are gated behind a Platform Feature and marked accordingly - if a feature is disabled on your account, the command fails fast with an explanatory error rather than a confusing API error.

Auth & session

canopy login [--manual] [--api-key <key>] [--api-url <url>] [--app-url <url>]
canopy logout
canopy whoami
canopy profile list
canopy profile use <name>
canopy profile rm <name>
canopy account totp status|enroll|confirm|disable [code]
canopy account change-password <current_password> <new_password>

Projects & environments

canopy projects list
canopy projects create <name> [--team <slug>]

canopy environments list --project <slug>
canopy environments create <branch> --project <slug> [--repository <repo>]
  [--template <template_id>] [--var NAME=value] [--parent <environment_id>]
  [--name <name>] [--build-path <dir>] [--build-command <cmd>]
  [--migrate-command <cmd>] [--host <dokku_host_id>]
canopy environments show <environment_id>
canopy environments update <environment_id> [--build-path <dir>] [--build-command <cmd>]
  [--migrate-command <cmd>] [--uses-artifact-deploy true|false] [--start-command <cmd>]
canopy environments rm <environment_id>
canopy environments logs --env <environment_id> [--access|--error]

Templates

canopy templates list
canopy templates show <template_id>
canopy templates save <environment_id> --name <name> [--slug <slug>]
  [--description <text>] [--visibility private|team|global] [--var NAME]
canopy templates create <name> [--slug <slug>] [--repository <repo>]
  [--visibility <v>] [--description <text>] [--team <slug>]
canopy templates set-services <template_id> --file <services.json>
canopy templates update <template_id> [--name <name>] [--description <text>]
  [--build-path <dir>] [--build-command <cmd>]
canopy templates rm <template_id>
canopy templates resync <template_id>
canopy templates admin-pending
canopy templates admin-approve <template_id>
canopy templates admin-reject <template_id> [--description <note>]

Domains, webhooks, storage, databases, variables, build steps

canopy domains list --env <environment_id>
canopy domains add <domain> --env <environment_id>
canopy domains rm <domain_id> --env <environment_id>
canopy domains ssl-enable --env <environment_id>

canopy webhooks list --env <environment_id>
canopy webhooks create --env <environment_id>
canopy webhooks secure --env <environment_id>
canopy webhooks rm <hook_id> --env <environment_id>
canopy webhooks deliveries --env <environment_id> [--limit <n>]

canopy storage list --env <environment_id>
canopy storage mount <host_path> <container_path> --env <environment_id>
canopy storage unmount <storage_mount_id> --env <environment_id>

Forest environments use volumes instead of host storage mounts:

canopy volumes list --env <environment_id>
canopy volumes create <name> --mount <path> --env <environment_id> [--size-gb <n>] [--process <name>] [--retention-days <n>] [--no-apply]
canopy volumes update <volume> --env <environment_id> [--mount <path>] [--process <name>] [--retention-days <n>] [--no-apply]
canopy volumes detach <volume> --env <environment_id> [--no-apply]
canopy volumes attach <volume> --env <environment_id> [--no-apply]
canopy volumes purge <volume> --env <environment_id> --confirm <volume name>
canopy volumes retained --env <environment_id>
canopy volumes adopt <volume_id> --mount <path> --env <environment_id> [--name <name>] [--process <name>] [--no-apply]

Checking, running and seeing how an app is doing:

canopy compose import <docker-compose.yml> --project <slug> [--apply]
canopy check --env <environment_id>
canopy state --env <environment_id>
canopy pods --env <environment_id>
canopy jobs list --env <environment_id> [--kind cron|run|release] [--limit <n>]
canopy run --env <environment_id> [--process <name>] [--with-volumes] -- <command...>
canopy services create <name> --engine <postgres|redis|external> --env <environment_id> [--size-gb <n>] [--replicas <n>]
canopy services restore <service_id> --backup <backup_id> --name <new_name> --env <environment_id> [--target-time <ISO 8601>]
canopy environments update <environment_id> --predeploy-backup <true|false>
canopy registries add --team <team_id> --host <registry_host> --credential-file <path>

Image environments, application configuration and deleting an environment that holds state:

canopy environments create <name> --project <slug> --image <reference>
canopy environments create <branch> --project <slug> --image <reference> --repository <owner/repo>
canopy environments update <environment_id> --health-mode <auto|tcp|http|legacy_root_2xx> [--backup-consistency <stopped|online>]
canopy deploys create --env <environment_id> --image <reference>
canopy config get|revisions --env <environment_id>
canopy config apply -f <canopy.yml> --env <environment_id> [--no-apply]
canopy environments rm <environment_id> [--plan] [--confirm <slug>] [--volumes <retain|delete>] [--databases <retain|delete>]

Databases and variables:

canopy database show --env <environment_id>
canopy database create <type> --env <environment_id> [--image <image>] [--image-version <tag>]
canopy database rm --env <environment_id>
canopy test-database show|create <type>|rm --env <environment_id>

canopy variables list --env <environment_id> [--reveal]
canopy variables set <NAME> <VALUE> --env <environment_id>
canopy variables rm <NAME> --env <environment_id>

canopy build-steps list --env <environment_id>
canopy build-steps add <command> --env <environment_id>
canopy build-steps rm <step_id> --env <environment_id>
canopy build-steps mv <step_id> --direction up|down --env <environment_id>

<type> is psql, mariadb, or mongo - see Databases. A successful deploy enables SSL automatically for any custom domain without it yet; domains ssl-enable just forces an immediate retry.

Deploys & builds

canopy deploys list --env <environment_id> [--page <n>]
canopy deploys create --env <environment_id>
canopy deploys logs <build_id> [--follow]
canopy deploys cancel <build_id>
canopy deploys rollback <build_id>
canopy deploys unlock --env <environment_id> [--force]
canopy builds trace <build_id> --env <environment_id>

Deploys also trigger automatically on a push to a linked branch.

Teams, billing, repositories, keys

canopy teams list
canopy teams create <name> [--member <email> ...]
canopy teams rm <team_id>
canopy teams billing <team_id>
canopy teams invite <team_id> --email <email> [--role developer|owner]
canopy teams uninvite <team_id> <invite_id>
canopy teams set-role <team_id> <user_id> --role <role>
canopy teams remove-member <team_id> <user_id>
canopy teams failure-signature-sharing <team_id> [--enable|--disable]
canopy teams failure-signatures <team_id>
canopy teams debt-benchmark-sharing <team_id> [--enable|--disable]

canopy repositories list [--q <search>]

canopy billing plans
canopy billing plan
canopy billing checkout <plan> --success-url <url> --cancel-url <url>
canopy billing portal [--return-url <url>]

canopy keys list
canopy keys create <name>
canopy keys revoke <key_id>

Releases, artifacts, promotions, policies, audit

canopy releases list --project <id>
canopy releases show <release_id> --project <id>
canopy releases create --project <id> --version <v> --artifact <artifact_id> [repeatable] [--notes <text>]
canopy releases promote <release_id> --environment <id>
canopy releases approve <promotion_id> --environment <id>

canopy artifacts list --team <id>
canopy artifacts show <artifact_id>
canopy artifacts impact <digest|commit|package> --team <id> [--by digest|commit|package]
canopy artifacts passport <artifact_id>

canopy policies list --team <id>
canopy policies show <policy_id> --team <id>
canopy policies simulate <policy_id> --team <id> [--limit <n>]
canopy policies enable|disable <policy_id> --team <id>

canopy audit list --team <id>
canopy audit verify --team <id>
canopy audit export --team <id> [--out <file>]

Gated behind host.releases/host.promotion_policies respectively.

SSO, SCIM, agents

canopy sso status --team <team_id>
canopy sso test --team <team_id>
canopy scim token rotate --team <team_id>
canopy scim token revoke --team <team_id>

SAML connection setup itself (IdP entity ID, SSO URL, certificate) is done once in the dashboard (Team settings → Security), which shows the metadata/ACS URLs to give your IdP. sso test checks the connection is enabled and complete, without driving a real IdP login. scim token rotate prints the new plaintext provisioning token exactly once and invalidates the previous one immediately. Gated behind host.sso.

canopy agents list --team <id>
canopy agents create <name> --team <id> --kind maintenance|review|docs|custom
  [--permission <action> ...]
canopy agents enable|disable <agent_id> --team <id>
canopy agents key <agent_id> --team <id> [--expires-in-ms <ms>]
canopy agents runs <agent_id> --team <id>

Scoped agent identities for automation - not feature-gated (rides a per-team enabled column instead).

Marketplace & MCP hosting

canopy catalog search [--q <query>]
canopy catalog list
canopy catalog show <workflow_id>
canopy catalog create <name> --namespace <id> --slug <slug> [--description <text>]
canopy catalog publish <workflow_id> --version <v> --steps-json <json>
canopy catalog verify <workflow_id> --verified <bool>
canopy catalog metrics <workflow_id>
canopy catalog install <workflow_id> [--granted-permission <perm> ...]
canopy catalog uninstall <workflow_id>
canopy catalog installations
canopy catalog run <installation_id>

Gated behind host.marketplace.

canopy mcp list
canopy mcp show <server_id>
canopy mcp create <name> --namespace <id> --slug <slug> [--visibility <v>]
canopy mcp publish <server_id> --version <v> --artifact <id> --tools-json <json>
  [--required-credential <name> ...]
canopy mcp start|stop <server_id>
canopy mcp set-credential <server_id> <key> --value <v>
canopy mcp install <namespace_scope>/<slug>
canopy mcp invoke <server_id> <tool_name>

Gated behind host.mcp.hosting (preview). This is Canopy’s hosted third-party MCP server marketplace, not a client for Canopy’s own MCP servers - see MCP.

Canopy Connect (CI) & timeline

canopy ci report [--connection <id>] [--status <status>] [--env <environment_id>] [--commit <sha>]
canopy ci connections list --team <id>
canopy ci connect --team <id> --provider <id> --repo <host/owner/name>
canopy ci runs list --pipeline <id>
canopy ci runs show <run_id>
canopy ci discover <connection_id>
canopy ci validate [--file <path>]

canopy timeline --env <environment_id> [--cursor <cursor>]

Gated behind host.ci (ga, enabled). See Canopy Connect for the full connection → discovery → run lifecycle.

Costs & budgets

canopy costs summary --team <id>
canopy costs breakdown --team <id>
canopy costs anomalies --team <id> [--threshold <n>]
canopy costs export [--format json|csv] --team <id> [--since <date>] [--until <date>]

canopy budgets list --team <id>
canopy budgets set --team <id> [--id <id>] [--project <id>] [--environment <id>]
  [--limit <n>] [--currency <code>] [--disable]
canopy budgets delete <budget_id> --team <id>

Gated behind host.budgets.

Alerts (preview)

canopy alerts list [--space <id-or-slug>]
canopy alerts create <name> --metric <metric> --threshold <n>
  --channel <in_app|webhook> [--webhook-url <url>] [--space <id-or-slug>]
canopy alerts delete <rule_id> [--space <id-or-slug>]
canopy alerts events [--space <id-or-slug>]

--metric is one of open_incidents_count, budget_percent_used, deploy_lag_minutes, or failed_ci_runs_on_default_branch. --webhook-url is required when --channel webhook. Rules are evaluated on the API’s own schedule - creating one does not fire it, and a rule resolves on its own when the metric drops back below its threshold.

Incidents, notifications, recommendations

canopy incidents list <environment_id>
canopy incidents show|mitigate|resolve|dismiss <environment_id> <incident_id>

canopy notifications list [--limit <n>] [--offset <n>]
canopy notifications read <notification_id>
canopy notifications read-all

canopy recommendations list
canopy recommendations inbox <environment_id|team_id>
canopy recommendations apply|dismiss|revert <environment_id> <recommendation_id>

recommendations (host.operational_recommendations) is fully enabled. incidents and notifications exist in the CLI and API but are currently disabled in production (host.incidents, host.notifications - see Platform Features) - expect a “feature disabled” error against api.canopy.pm today.

Maintenance

canopy maintenance list <team_id> <repository_id>
canopy maintenance show <team_id> <repository_id> <task_id>
canopy maintenance enable|disable <team_id> <repository_id> [category]
canopy maintenance budget <team_id> <repository_id> <category> <cents>
canopy maintenance run <team_id> <repository_id> <category> <proposal_json> <estimated_cost_cents>
  [--agent-identity-id <id>]

Currently disabled in production (host.automation.maintenance, experimental) - implemented, not yet launched.

Compliance & residency

canopy compliance status <team_id>
canopy compliance assemble <team_id> <period_start> <period_end>
canopy compliance export <team_id> <package_id>
canopy compliance legal-review <team_id> <package_id>

canopy residency show|attest <environment|artifact> <id>

Gated behind host.compliance (preview, internal - not in navigation). residency specifically (host.compliance.residency_chain) is currently disabled in production.

Docker images

canopy images login [--team <id>] [--name <n>] [--read-only] [--expires-in-days <n>] [--print]
canopy images pin <namespace>/<name>[:tag] --team <id>
canopy images lock <canopy.pipeline.ts> --team <id> [--update] [--check]
canopy images list --team <id> [--limit <n>]

See Package Registry.

Registry (npm packages)

canopy registry login --scope <@scope>
canopy registry publish [--tag <tag>] [--dry-run]
canopy registry list --team <id>
canopy registry info <@scope/name>
canopy registry stats <@scope/name>
canopy registry daily-pulls <@scope/name> <version> [--since-days <n>]

canopy registry dist-tag ls <@scope/name>
canopy registry dist-tag add <@scope/name@version> <tag>
canopy registry dist-tag rm <@scope/name> <tag>

canopy registry namespace create <@scope> --team <id>
canopy registry namespace verify <id> --team <id> --domain <domain>
canopy registry namespace status <id> --team <id>
canopy registry namespace public <id> --team <id> [--private]

Gated behind host.registry.

login writes a managed block into ./.npmrc and is safe to re-run (it rewrites its own block rather than appending). After that, publish a new version with the real npm client - npm version patch && npm publish, or npm publish --tag next for a prerelease that shouldn’t move latest. Versions are immutable: republishing one is a 409, and there is no unpublish.

namespace public makes a whole scope installable with no Canopy credential at all - how you’d ship an SDK to your own customers. See Package Registry for the full workflow.

Engineering Graph & Spaces (preview)

canopy graph node <ref>
canopy graph edges <ref> [--depth <0-3>]
canopy graph commit <sha>

canopy space list
canopy space create <name>
canopy space use <id-or-slug>
canopy space current
canopy space search <query> [--space <id-or-slug>] [--kinds k1,k2]
canopy space monitor [--space <id-or-slug>]
canopy space ask <question> [--space <id-or-slug>]

Both gated behind preview-lifecycle features (host.graph, host.spaces) - enabled by default, but not a locked contract yet. See Spaces.

Platform Features (staff-only)

canopy features list
canopy features set <key> enabled|disabled --reason "..."

See Platform Features.

Admin (staff/operational)

canopy admin update-host-script <filename> [--file <path>]
canopy admin network-selftest
canopy admin network-attach <environment_id> <network_name>
canopy admin docker-options-report <environment_id> [--phase build|deploy|run]
canopy admin mcp-network-selftest
canopy admin hosts list
canopy admin hosts add <hostname> [--ssh-port <n>] [--bootstrap-ssh-user <user>]
  [--bootstrap-ssh-port <n>] [--bootstrap-key-path <path>]
canopy admin hosts set-status <id> active|draining|disabled
canopy admin hosts update-connection <id> [--hostname <h>] [--ssh-port <n>]
canopy admin hosts health-check <id>
canopy admin analytics overview|events [--event <name>]|users|revenue [--days <n>]
canopy admin stripe plans
canopy admin stripe set-plan <id> [--stripe-price-id <id>] [--stripe-product-id <id>]
canopy admin builder [--limit <n>]
canopy admin backups status|browse [--path <p>]|quota|size <path>
canopy admin reconciliation
canopy admin missing-apps
canopy admin repair-missing-app <environment_id>
canopy admin builds-kill [--all]
canopy admin host-scripts status
canopy admin observability status

Not feature-gated (foundational/staff-operational surface): projects, environments, deploys, domains, variables, teams, billing, keys, admin, storage, database, agents.