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.
Create and inspect a deployment
Section titled “Create and inspect a deployment”canopy projects listcanopy projects create my-app --from-repo owner/repositorycanopy environments list --project my-appcanopy 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.
Manage groups
Section titled “Manage groups”canopy groups listcanopy groups treecanopy groups show paymentscanopy groups create Payments --parent engineering --contact "#payments"canopy groups add payments ada@example.com --maintainercanopy groups remove payments ada@example.comcanopy groups move payments --rootcanopy groups rename payments Billingcanopy groups delete billingcanopy groups minecanopy groups maintainers paymentsA 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.
Give a group keys, channels and agents
Section titled “Give a group keys, channels and agents”canopy keys create deploy-bot --group payments --resource-scope graph:project:<id> --can environment:deploy --expires-at 2027-06-01T00:00:00Z --scope ci:writecanopy keys list --group paymentscanopy keys revoke <key-id> --group paymentscanopy channels add payments https://example.com/hook --events build.failed,deployment.failed_terminalcanopy channels list paymentscanopy 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.
Give access
Section titled “Give access”canopy access grant --group payments --project fleet-api --role developercanopy access grant --user ada@example.com --actions environment:approve_deploy --expires 2027-01-01canopy access list --project fleet-apicanopy access explain --project fleet-api --action environment:deploycanopy access owners fleet --role developer --scope environmentscanopy access review --days 30canopy 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.
Inspect a System
Section titled “Inspect a System”canopy systems listcanopy systems show <system-id>canopy systems activity <system-id> --limit 20canopy systems suggestionscanopy 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.
Owners and watchers of a System
Section titled “Owners and watchers of a System”canopy systems owners list checkoutcanopy systems owners add checkout --group paymentscanopy systems owners add checkout ada@example.comcanopy systems owners remove checkout --group paymentscanopy systems watchers add checkout gracecanopy systems watch checkoutcanopy systems unwatch checkoutcanopy systems minecanopy systems contact checkout "#checkout"canopy systems contact checkout --clearcanopy systems timeline checkout --days 3canopy systems role checkout checkout-staging stagingcanopy systems role checkout checkout-staging --clearcanopy systems relations checkoutcanopy systems delivery checkoutcanopy systems push-impact --repository acme/checkout --branch maincanopy systems gate checkout holdcanopy 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.
Read logs and manage secrets
Section titled “Read logs and manage secrets”canopy environments logs --env <environment-id> --tailcanopy variables list --env <environment-id>canopy variables set DATABASE_URL '<value>' --env <environment-id> --secretAvoid printing secret values in shared terminals or CI logs. The CLI masks values by default; use its explicit reveal option only when needed.
Host and Cortex tools
Section titled “Host and Cortex tools”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.
MCP commands
Section titled “MCP commands”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.
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 identity and provisioning
Section titled “Team identity and provisioning”Team owners can inspect and test SAML configuration, and rotate or revoke the SCIM provisioning token:
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.