CLI Authentication

API Keys

The ZevCloud CLI authenticates using API keys — not your ZevID password.

Generating a Key

1. Go to Dashboard → Settings → API Keys
2. Enter a name (e.g., “My Laptop CLI”)
3. Pick a scope (use the lowest one that lets the CLI do its job):
   • Read — list and inspect projects, services, deployments, logs. No mutations.
   • Deploy — everything Read can do, plus trigger deployments, restart/stop services, and set/delete env vars. The right choice for CI pipelines and AI coding agents.
   • Full — equivalent to a human admin. Needed for creating or deleting projects, services, environments, or running terminal commands inside containers.
4. Click Generate Key
5. Copy the key immediately — the raw value is shown only once

The dashboard shows a permissions table that lists every action each scope can do. Use it to pick the right scope.

Login

CLI

zevcloud login

Paste the key when prompted. The CLI validates it and stores it locally at ~/.config/zevcloud.

Working with multiple teams

API keys are team-scoped — one key authenticates against one team. If you’re a member or admin of more than one team, generate an API key in each one and add them all to the CLI:

CLI

# Add Team A zevcloud login # Later, add Team B without losing Team A zevcloud login # See what's configured zevcloud team list # Switch the active team (interactive picker) zevcloud team switch # Or switch directly by name zevcloud team switch acme-corp # Run a single command against a non-active team without switching zevcloud --team acme-corp deploy a1b2c3d4-...

zevcloud logout removes only the active team. To wipe every configured team, use zevcloud logout --all.

Things the CLI cannot do, even with full

A handful of actions always require interactive authentication and are not reachable from the CLI:

• Creating, listing, or revoking API keys themselves
• Deleting a team or transferring ownership
• Inviting, removing, or changing a member’s role
• Buying or transferring a domain
• Setting team currency or upgrading a plan
• Opening the database GUI
• Connecting GitHub

If the CLI returns 403 — This action requires interactive authentication, that’s the cause. Open the dashboard and do it there.

Security model

• API keys are stored locally in ~/.config/zevcloud. They are never sent anywhere except the ZevCloud API.
• Every key is bound to the team member who created it. If that member leaves the team or is removed, the key is auto-revoked on its next use. Rotate the key (have a current member create a fresh one) when handing off.
• A key’s scope is fixed at creation — it cannot be promoted or demoted later. Issue a new key and revoke the old one.
• The creator’s current role on the team is the ceiling on what the key can do. A demoted creator means a demoted key, even without a re-issue.
• Revoke compromised keys immediately from the dashboard.
• For CI pipelines and AI agents, use Deploy scope unless you know you need more.