Skip to content

Host CLI

Install the Host CLI with npm install -g @canopy/cli. Authenticate with canopy login, then run canopy whoami to confirm the active account. Use canopy --help for the installed release’s complete command and flag reference; command groups also accept --help.

The CLI is the executable source of truth for the full command surface. This page keeps a few common workflows rather than duplicating every command and option.

Terminal window
canopy projects list
canopy projects create my-app --from-repo owner/repository
canopy environments list --project my-app
canopy deploys list --env <environment-id>
canopy state --env <environment-id>

The create command can provision a project and deploy a linked repository as one operation. Use canopy projects create --help and canopy environments create --help to see options supported by your installed version.

Terminal window
canopy groups list
canopy groups tree
canopy groups show payments
canopy groups create Payments --parent engineering --contact "#payments"
canopy groups add payments ada@example.com --maintainer
canopy groups remove payments ada@example.com
canopy groups move payments --root
canopy groups rename payments Billing
canopy groups delete billing
canopy groups mine
canopy groups maintainers payments

A group is its id, slug or name; pass --team <team-id> when you belong to several Organizations. A user for add and remove is an id, an email or a username of an Organization member. list takes --query <text>, create takes --description and --contact, and every command takes --json. Creating, renaming, moving and deleting groups needs the group:manage permission; maintainers of a group, or of a group above it, manage its members. A group that has subgroups cannot be deleted. See Groups.

Terminal window
canopy keys create deploy-bot --group payments --resource-scope graph:project:<id> --can environment:deploy --expires-at 2027-06-01T00:00:00Z --scope ci:write
canopy keys list --group payments
canopy keys revoke <key-id> --group payments
canopy channels add payments https://example.com/hook --events build.failed,deployment.failed_terminal
canopy channels list payments
canopy channels remove payments <channel-id>
canopy agents group <agent-id> payments --team <team-id>

A group key needs --resource-scope, --can and --expires-at; it never does more than the group’s access gives, and it outlives you. A channel gets only the events of environments the group owns or watches through a System. An agent’s group is attribution only. See Groups.

Terminal window
canopy access grant --group payments --project fleet-api --role developer
canopy access grant --user ada@example.com --actions environment:approve_deploy --expires 2027-01-01
canopy access list --project fleet-api
canopy access explain --project fleet-api --action environment:deploy
canopy access owners fleet --role developer --scope environments
canopy access review --days 30
canopy access revoke <binding-id>

grant gives a group (--group) or a person (--user) a role (--role viewer, developer or admin) or a list of actions (--actions) on a project (--project), an environment (--environment) or, with neither, the whole Organization. list narrows with --project, --environment, --group and --user. explain lists what you can do in a scope and which role or binding allows each action. owners gives a System’s owning groups a role on its environments or on its projects (--scope). review sums up what turning enforcement on would have changed, from the requests that were recorded while it was off, and says whether every one is explained by a binding (--days, 1 to 90). Every command takes --team when you belong to several Organizations and --json. You need access:manage there and can only give what you hold. See Access.

Terminal window
canopy systems list
canopy systems show <system-id>
canopy systems activity <system-id> --limit 20
canopy systems suggestions
canopy systems keep <fingerprint>
canopy systems dismiss <fingerprint>

systems list shows each System of your Organization with its health, the reason code and its environment count (--team <team-id> when you belong to several Organizations). systems show adds every environment with the reason it is not healthy. systems activity pages the recent changes across the System’s environments; pass the printed --cursor for the next page. All three take --json. systems suggestions shows groupings Canopy found from your projects, domains and address variables, each with a fingerprint; keep creates the System with those environments (under --name if you give one) and dismiss hides the grouping for your Organization. See Systems for how groupings are found. They read the same data as the Systems page, so an API key limited to one project or environment cannot use them.

Terminal window
canopy systems owners list checkout
canopy systems owners add checkout --group payments
canopy systems owners add checkout ada@example.com
canopy systems owners remove checkout --group payments
canopy systems watchers add checkout grace
canopy systems watch checkout
canopy systems unwatch checkout
canopy systems mine
canopy systems contact checkout "#checkout"
canopy systems contact checkout --clear
canopy systems timeline checkout --days 3
canopy systems role checkout checkout-staging staging
canopy systems role checkout checkout-staging --clear
canopy systems relations checkout
canopy systems delivery checkout
canopy systems push-impact --repository acme/checkout --branch main
canopy systems gate checkout hold
canopy systems drift checkout dismiss <key>

A System is its id, slug or name; a user is an id, an email or a username of an Organization member; a group for --group is its id, slug or name. Pass --team <team-id> when you belong to several Organizations, and --json for the data. watchers takes list, add and remove like owners. Changing owners, the contact, or who else watches needs the system:manage permission; watching yourself needs only read access. timeline lists what changed across the System in your local time, with who did it and the groups that own it; role sets what an environment is for in a System (production, staging, development or preview) or clears it with --clear, and needs system:manage. relations shows what the System depends on and what uses it with the other Systems’ owners, delivery each environment’s newest build and what is held behind a failed staging build, push-impact what a push to a branch would rebuild, drift dismisses or restores a drift note by the key relations prints (needs system:manage), and gate (hold or off, needs system:manage) makes production deploys wait while staging has failed to build the commit. Owning or watching grants no access. See Systems.

Terminal window
canopy environments logs --env <environment-id> --tail
canopy variables list --env <environment-id>
canopy variables set DATABASE_URL '<value>' --env <environment-id> --secret

Avoid printing secret values in shared terminals or CI logs. The CLI masks values by default; use its explicit reveal option only when needed.

The canopy CLI manages Host projects and runtime resources. Cortex has a separate cortex CLI for knowledge spaces, ingestion, assistants, evaluation and Cortex MCP setup; see the Cortex CLI guide. The two CLIs authenticate against their respective APIs and authorization systems.

See MCP Servers for configuring Host and Cortex tool servers. Installing or enabling an MCP tool does not grant the caller additional permissions.

The Host CLI has two separate MCP workflows. mcp connect registers the customer-facing Host MCP server in a local .mcp.json and creates a dedicated revocable Host API key. The hosted-server commands manage preview marketplace metadata; starting or invoking a hosted server is not currently available.

Terminal window
canopy mcp connect --team <team-id> --target .
canopy mcp list --team <team-id>
canopy mcp show <server-id> --team <team-id>
canopy mcp install <namespace>/<slug> --team <team-id>

The hosted MCP registry is generally available. Listing, inspecting, registering servers, publishing version metadata, and setting credentials are implemented. canopy mcp start and canopy mcp invoke currently return an unavailable error because server execution is not implemented. Use the separately connected Host or Cortex MCP server for agent tools; the hosted registry is not a generic MCP protocol endpoint. Run canopy mcp <command> --help for the installed release’s flags. The server enforces team permissions regardless of which CLI command is available.

Team owners can inspect and test SAML configuration, and rotate or revoke the SCIM provisioning token:

Terminal window
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>

The SCIM token is shown only when created. See SAML SSO and SCIM for setup and credential handling.