From fc5125a5ec4e1d6661bf66776e85d8d66e29848a Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 23 Mar 2026 18:30:03 +0000 Subject: [PATCH 1/2] Add CLI documentation page to Electric Cloud section Adds a new docs page for the @electric-sql/cli package covering installation, authentication methods, common workflows, and environment variables. https://claude.ai/code/session_015Cs3AVXi49dg5x2fo2XrXL --- website/.vitepress/config.mts | 1 + website/cloud/cli.md | 110 ++++++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 website/cloud/cli.md diff --git a/website/.vitepress/config.mts b/website/.vitepress/config.mts index 1316809c80..0d74a9419b 100644 --- a/website/.vitepress/config.mts +++ b/website/.vitepress/config.mts @@ -193,6 +193,7 @@ export default defineConfig({ { text: 'Usage', link: '/cloud/usage' }, { text: 'Protocols', link: '/cloud/protocols' }, { text: 'Pricing', link: '/cloud/pricing' }, + { text: 'CLI', link: '/cloud/cli' }, ], }, ], diff --git a/website/cloud/cli.md b/website/cloud/cli.md new file mode 100644 index 0000000000..5ffc0a2d82 --- /dev/null +++ b/website/cloud/cli.md @@ -0,0 +1,110 @@ +--- +title: CLI +description: >- + Command-line interface for managing Electric Cloud resources. +image: /img/meta/electric-cloud.jpg +outline: deep +--- + + + +# CLI + +Command-line interface for [Electric Cloud](https://dashboard.electric-sql.cloud) — manage workspaces, projects, environments, and services from the terminal. The CLI provides full control over your Electric Cloud resources, from provisioning Postgres sync services to managing per-PR environments in CI/CD pipelines. All commands support JSON output for scripting and automation. + +## Installation + +Install globally: + +```shell +npm install -g @electric-sql/cli +``` + +Or run directly with `npx`: + +```shell +npx @electric-sql/cli --help +``` + +## Authentication + +The CLI checks for credentials in this order: + +### 1. `--token` flag + +Pass a token directly for one-off commands or scripts: + +```shell +electric projects list --token sv_live_... +``` + +### 2. `ELECTRIC_API_TOKEN` environment variable + +Set a token in your environment for CI/CD pipelines: + +```shell +export ELECTRIC_API_TOKEN=sv_live_... +electric projects list +``` + +### 3. Browser login + +For interactive use, log in via OAuth: + +```shell +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. + +## Provision a Postgres sync service + +```shell +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 + +```shell +electric services get-secret svc_abc +``` + +## Per-PR environments + +```shell +# Create an environment for the PR +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 when the PR is closed +electric environments delete "$ENV_ID" --force +``` + +## Environment variables + +| Variable | Description | +|----------|-------------| +| `ELECTRIC_API_TOKEN` | API token for authentication | +| `ELECTRIC_WORKSPACE_ID` | Default workspace ID | +| `ELECTRIC_API_URL` | Override API base URL | + +## JSON output + +All commands support `--json` for machine-readable output: + +```shell +electric projects list --json +``` + +Destructive commands (`delete`, `revoke`) require `--force` when using `--json` since there is no interactive prompt. From cb2f3d5cb7c304116a3618f5d810263c31e5386c Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 25 Mar 2026 13:03:06 +0000 Subject: [PATCH 2/2] Update CLI docs: reorder auth, add durable streams example - Move browser login to first auth method - Add durable streams provisioning example - Mention durable streams in page description https://claude.ai/code/session_015Cs3AVXi49dg5x2fo2XrXL --- website/cloud/cli.md | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/website/cloud/cli.md b/website/cloud/cli.md index 5ffc0a2d82..00e344240c 100644 --- a/website/cloud/cli.md +++ b/website/cloud/cli.md @@ -1,7 +1,7 @@ --- title: CLI description: >- - Command-line interface for managing Electric Cloud resources. + Command-line interface for managing Electric Cloud resources, including Postgres sync services and durable streams. image: /img/meta/electric-cloud.jpg outline: deep --- @@ -10,7 +10,7 @@ outline: deep # CLI -Command-line interface for [Electric Cloud](https://dashboard.electric-sql.cloud) — manage workspaces, projects, environments, and services from the terminal. The CLI provides full control over your Electric Cloud resources, from provisioning Postgres sync services to managing per-PR environments in CI/CD pipelines. All commands support JSON output for scripting and automation. +Command-line interface for [Electric Cloud](https://dashboard.electric-sql.cloud) — manage workspaces, projects, environments, and services from the terminal. The CLI provides full control over your Electric Cloud resources, from provisioning [Postgres sync](/products/postgres-sync) services and [durable streams](/products/durable-streams) to managing per-PR environments in CI/CD pipelines. All commands support JSON output for scripting and automation. ## Installation @@ -30,14 +30,16 @@ npx @electric-sql/cli --help The CLI checks for credentials in this order: -### 1. `--token` flag +### 1. Browser login -Pass a token directly for one-off commands or scripts: +For interactive use, log in via OAuth: ```shell -electric projects list --token sv_live_... +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. + ### 2. `ELECTRIC_API_TOKEN` environment variable Set a token in your environment for CI/CD pipelines: @@ -47,16 +49,14 @@ export ELECTRIC_API_TOKEN=sv_live_... electric projects list ``` -### 3. Browser login +### 3. `--token` flag -For interactive use, log in via OAuth: +Pass a token directly for one-off commands or scripts: ```shell -electric auth login +electric projects list --token sv_live_... ``` -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. - ## Provision a Postgres sync service ```shell @@ -68,6 +68,14 @@ electric services create postgres \ --region us-east-1 ``` +## Provision a durable streams service + +```shell +electric services create streams \ + --environment env_abc \ + --region us-east-1 +``` + ## Fetch service credentials ```shell