@electric-sql/cli

--- 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.