Electric Cloud CLI

Command-line interface for Electric Cloud — manage workspaces, projects, environments, and services from the terminal.

Installation

npm install -g @electric-sql/cli

Or run directly with npx:

npx @electric-sql/cli --help

Quick Start

# Log in via browser
electric auth login

# List your workspaces
electric workspaces list

# Create a project
electric projects create --name "my-app"

# Provision a Postgres sync service
electric services create postgres \
  --environment env_abc \
  --database-url "postgresql://postgres:password@localhost:64323/electric" \
  --region us-east-1
  --wait

Authentication

The CLI supports three authentication methods, checked in this order:

1. --token flag

Pass a token directly for one-off commands or scripts:

electric projects list --token sv_live_...

2. ELECTRIC_API_TOKEN environment variable

Set a token in your environment for CI/CD pipelines:

export ELECTRIC_API_TOKEN=sv_live_...
electric projects list

3. Browser login

For interactive use, log in via OAuth:

electric auth login

This opens the Electric Cloud dashboard in your browser. After authenticating, your session is stored locally at ~/.config/electric/auth.json and is valid for 7 days.

Creating API tokens

Tokens are created with specific scopes that control what they can access:

electric auth token create \
  --name "ci-deploy" \
  --scopes v2:services:read,v2:services:write

The token value is displayed once at creation and cannot be retrieved again.

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.

Commands

Run electric --help for the full command list, or electric <command> --help for details on any command.

electric [--json] [--token <token>]
├── auth
│   ├── login                      Log in via browser OAuth
│   ├── logout                     Clear stored credentials
│   ├── whoami                     Show current auth context
│   └── token
│       ├── create                 Create an API token
│       ├── list                   List tokens in a workspace
│       └── revoke <token-id>     Revoke a token
├── workspaces
│   ├── list                       List accessible workspaces
│   └── get <workspace-id>        Get workspace details
├── projects
│   ├── list                       List projects
│   ├── create                     Create a project
│   ├── get <project-id>          Get project details
│   ├── update <project-id>       Rename a project
│   └── delete <project-id>       Delete a project
├── environments
│   ├── list                       List environments in a project
│   ├── create                     Create an environment
│   ├── get <environment-id>      Get environment details
│   ├── update <environment-id>   Rename an environment
│   └── delete <environment-id>   Delete an environment
├── services
│   ├── list                       List services in an environment
│   ├── get <service-id>          Get service details
│   ├── update <service-id>       Rename a service
│   ├── delete <service-id>       Delete a service
│   ├── get-secret <service-id>   Get service credentials
│   └── create
│       ├── postgres               Create a Postgres sync service
│       ├── streams                Create a durable streams service
│       └── proxy                  Create a proxy service
└── claimable
    ├── create                     Provision a Postgres database with Sync
    ├── status <claim-id>         Check provisioning status
    └── claim <claim-id>          Claim a provisioned service into your workspace

Global flags

| Flag | Description | |------|-------------| | --json | Output as JSON (for scripting and CI) | | --token <token> | Use this API token for authentication | | --help | Show help for any command | | --version | Show CLI version |

Common Workflows

Provision a Postgres sync service

electric projects create --name "my-app"
electric environments create --project proj_abc --name "staging"
electric services create postgres \
  --environment env_abc \
  --database-url "postgresql://user:pass@host:5432/db" \
  --region us-east-1

Fetch service credentials

electric services get-secret svc_abc

Per-PR environments

# Create
ENV_ID=$(electric environments create \
  --project "$PROJECT_ID" --name "pr-$PR_NUMBER" \
  --json | jq -r '.id')

electric services create postgres \
  --environment "$ENV_ID" \
  --database-url "$DATABASE_URL" \
  --region us-east-1

# Tear down
electric environments delete "$ENV_ID" --force

Token management

electric auth token create --name "deploy-bot" --scopes v2:services:read,v2:services:write
electric auth token list
electric auth token revoke tok_abc --force

JSON Output

All commands support --json for machine-readable output:

electric projects list --json

Errors in JSON mode are written to stderr:

{ "error": "NOT_FOUND", "message": "Service not found", "exitCode": 3 }

Destructive commands (delete, revoke) require --force when using --json since there is no interactive prompt.

Environment Variables

| Variable | Description | |----------|-------------| | ELECTRIC_API_TOKEN | API token for authentication | | ELECTRIC_WORKSPACE_ID | Default workspace ID | | ELECTRIC_API_URL | Override API base URL |

Workspace Resolution

Commands that need a workspace resolve it automatically:

1. --workspace flag (if provided)
2. ELECTRIC_WORKSPACE_ID env var
3. API token → uses the token's bound workspace
4. User JWT with one workspace → auto-selected
5. Multiple workspaces → error with guidance

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error (network, unexpected API error) | | 2 | Authentication error (missing/invalid credentials) | | 3 | Resource not found | | 4 | Validation error (bad input, missing --force) | | 5 | Conflict (resource state prevents the operation) |

License

Apache-2.0