---
name: auth
description: >
  Authentication patterns for the Electric Cloud CLI. Three auth methods
  (--token flag, ELECTRIC_API_TOKEN env var, browser OAuth login), API token
  creation with scoped permissions, CI/CD non-interactive setup, token
  lifecycle (create, list, revoke), JWT expiry handling, and the auth
  resolution order.
type: core
library: electric-cli
library_version: "0.0.8"
requires:
  - getting-started
sources:
  - "electric-sql/electric:packages/cli/src/auth.ts"
  - "electric-sql/electric:packages/cli/src/config.ts"
  - "electric-sql/electric:packages/cli/src/commands/auth/login.ts"
  - "electric-sql/electric:packages/cli/src/commands/auth/token/create.ts"
---

This skill builds on electric-cli/getting-started. Read it first for setup basics.

# Electric Cloud CLI — Authentication

Three auth methods, checked in order: `--token` flag, `ELECTRIC_API_TOKEN` env
var, stored JWT from browser login. Use browser login for interactive work, API
tokens for CI/CD and scripts.

## Setup

```bash
# Interactive login — opens browser, stores JWT at ~/.config/electric/auth.json
electric auth login

# Check current auth context
electric auth whoami

# Create a scoped API token for automation
electric auth token create \
  --name "ci-deploy" \
  --scopes v2:services:read,v2:services:write
```

## Core Patterns

### CI/CD pipeline authentication

Use API tokens in CI — never browser login:

```bash
# In your CI environment
export ELECTRIC_API_TOKEN=sv_live_...

# All commands now authenticate via the token
electric services create postgres \
  --environment "$ENV_ID" \
  --database-url "$DATABASE_URL" \
  --region us-east-1 \
  --wait
```

API tokens are bound to a workspace, so workspace resolution is automatic.

### Scoped tokens with least privilege

Available scopes: `v2:projects:read`, `v2:projects:write`,
`v2:environments:read`, `v2:environments:write`, `v2:services:read`,
`v2:services:write`, `v2:services:secrets`, `v2:tokens:read`, `v2:tokens:write`.

```bash
# Read-only token for monitoring
electric auth token create \
  --name "monitor" \
  --scopes v2:services:read,v2:projects:read

# Deploy token that can create/update services but not delete projects
electric auth token create \
  --name "deployer" \
  --scopes v2:services:read,v2:services:write,v2:environments:read,v2:environments:write
```

The token value is shown once at creation. Store it securely — it cannot be
retrieved again.

### Token lifecycle management

```bash
# List all tokens in the workspace
electric auth token list

# Revoke a compromised or unused token
electric auth token revoke tok_abc
```

### Direct signup-to-token URL

New users can sign up and land directly on the token creation page:

```
https://dashboard.electric-sql.cloud/?intent=create&resource=token
```

This is useful in onboarding flows, README quick-starts, or agent-guided setup
where the user needs an API token immediately after creating an account.

### One-off commands with explicit token

```bash
# Use a different token for a single command without changing env
electric projects list --token sv_live_other_token
```

The `--token` flag takes highest priority, overriding both the env var and
stored JWT.

## Common Mistakes

### CRITICAL Using browser login in CI/CD

Wrong:

```bash
# In CI pipeline
electric auth login  # Hangs waiting for browser interaction!
```

Correct:

```bash
# In CI pipeline
export ELECTRIC_API_TOKEN=sv_live_...
electric projects list  # Works non-interactively
```

`electric auth login` requires an interactive browser. In CI, always use
`ELECTRIC_API_TOKEN` or `--token`.

Source: packages/cli/src/auth.ts

### HIGH Creating tokens with overly broad scopes

Wrong:

```bash
electric auth token create \
  --name "read-only-checker" \
  --scopes v2:projects:read,v2:projects:write,v2:services:read,v2:services:write,v2:services:secrets
```

Correct:

```bash
electric auth token create \
  --name "read-only-checker" \
  --scopes v2:projects:read,v2:services:read
```

Grant only the scopes the token actually needs. Tokens with write or secrets
access can modify or expose resources.

Source: packages/cli/README.md § Creating API tokens

### HIGH Ignoring JWT expiry warnings

Wrong:

```bash
electric auth whoami
# Warning: JWT expires in 2 hours
electric projects list  # Works now, but will fail in CI if cached
```

Correct:

```bash
electric auth whoami
# Warning: JWT expires in 2 hours
electric auth login  # Refresh the JWT
```

Browser JWTs expire after 7 days. The CLI warns 24 hours before expiry. If you
see the warning, re-login to avoid disruption.

Source: packages/cli/src/auth.ts

### MEDIUM Hardcoding tokens in scripts instead of using env vars

Wrong:

```bash
electric projects list --token sv_live_abc123  # Token visible in shell history
```

Correct:

```bash
export ELECTRIC_API_TOKEN=sv_live_abc123  # Or use CI secrets manager
electric projects list
```

Passing tokens via `--token` leaves them in shell history and process listings.
Prefer `ELECTRIC_API_TOKEN` env var, especially in shared environments.

Source: packages/cli/README.md § Environment Variables

## See also

- [getting-started](../getting-started/SKILL.md) — Installation and first deployment
- [claimable-resources](../claimable-resources/SKILL.md) — No-auth provisioning flow

For token command details, run `electric auth token --help`.

## Version

Targets @electric-sql/cli v0.0.8.