@electric-sql/cli

# Electric Cloud CLI Command-line interface for [Electric Cloud](https://dashboard.electric-sql.cloud) — manage workspaces, projects, environments, and services from the terminal. ## Installation ```bash npm install -g @electric-sql/cli ``` Or run directly with `npx`: ```bash npx @electric-sql/cli --help ``` ## Quick Start ```bash # 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: ```bash electric projects list --token sv_live_... ``` ### 2. `ELECTRIC_API_TOKEN` environment variable Set a token in your environment for CI/CD pipelines: ```bash export ELECTRIC_API_TOKEN=sv_live_... electric projects list ``` ### 3. Browser login For interactive use, log in via OAuth: ```bash 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: ```bash 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 ```bash 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 ```bash electric services get-secret svc_abc ``` ### Per-PR environments ```bash # 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 ```bash 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: ```bash electric projects list --json ``` Errors in JSON mode are written to stderr: ```json { "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](../../LICENSE)