---
title: 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](https://console.zevcloud.net/settings?tab=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

```bash
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:

```bash
# 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](https://console.zevcloud.net) 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.