---
name: getting-started
description: >
  First-time setup for the Electric Cloud CLI. Install @electric-sql/cli,
  authenticate with electric auth login, create your first project and
  environment, provision a service. Covers the resource hierarchy
  (workspace > project > environment > service), global flags (--json,
  --quiet, --token), and how to discover commands via --help.
type: lifecycle
library: electric-cli
library_version: "0.0.8"
sources:
  - "electric-sql/electric:packages/cli/README.md"
  - "electric-sql/electric:packages/cli/src/index.ts"
---

# Electric Cloud CLI — Getting Started

The Electric Cloud CLI (`electric`) manages workspaces, projects, environments,
and services on Electric Cloud. All resources follow a strict hierarchy:
**workspace > project > environment > service**.

## Setup

```bash
# Install globally
npm install -g @electric-sql/cli

# Or run via npx (no install)
npx @electric-sql/cli --help

# Log in — opens browser for OAuth
electric auth login

# Verify you're authenticated
electric auth whoami
```

## Core Patterns

### Resource hierarchy and first deployment

Every command operates within this hierarchy. Create resources top-down:

```bash
# List your workspaces (auto-resolved if you only have one)
electric workspaces list

# Create a project (workspace auto-selected if unambiguous)
electric projects create --name "my-app"

# Create an environment inside the project
electric environments create --project proj_abc --name "production"

# Provision a Postgres sync service
electric services create postgres \
  --environment env_abc \
  --database-url "postgresql://user:pass@host:5432/db" \
  --region us-east-1 \
  --wait
```

### Discovering commands with --help

The CLI is self-documenting. Use `--help` at any level to see available
commands, required arguments, and options:

```bash
electric --help                       # All top-level commands
electric services --help              # Service subcommands
electric services create postgres --help  # Full option list for postgres creation
```

Agents and scripts should use `--help` to learn the full set of options for
any command rather than guessing flags.

### Output modes for scripting

```bash
# JSON output — machine-readable, errors on stderr
electric projects list --json

# Quiet mode — prints only the primary resource ID
electric projects create --name "my-app" --quiet
# Output: proj_abc

# Pipe into other tools
PROJECT_ID=$(electric projects create --name "my-app" --quiet)
electric environments create --project "$PROJECT_ID" --name "staging" --quiet
```

### Workspace resolution

Most commands need a workspace. The CLI resolves it automatically:

1. `--workspace` flag (explicit)
2. `ELECTRIC_WORKSPACE_ID` env var
3. API token's bound workspace
4. Single workspace on account — auto-selected
5. Multiple workspaces — error with guidance

You rarely need to pass `--workspace` explicitly.

## Common Mistakes

### CRITICAL Skipping authentication before running commands

Wrong:

```bash
electric projects list
# Error: Not authenticated. Run `electric auth login` or set ELECTRIC_API_TOKEN.
```

Correct:

```bash
electric auth login    # Interactive — opens browser
# or
export ELECTRIC_API_TOKEN=sv_live_...  # Non-interactive (CI/scripts)
electric projects list
```

All commands except `claimable` require authentication. Log in first or set a token.

Source: packages/cli/README.md § Authentication

### HIGH Creating services without --wait and assuming they're ready

Wrong:

```bash
electric services create postgres --environment env_abc --database-url "..." --region us-east-1
# Immediately tries to use the service — but it's still provisioning
```

Correct:

```bash
electric services create postgres \
  --environment env_abc \
  --database-url "..." \
  --region us-east-1 \
  --wait
# Blocks until the service is active (or fails with a timeout)
```

Service provisioning is asynchronous. Use `--wait` to block until ready, or poll
`electric services get <id>` for the status.

Source: packages/cli/src/commands/services/create/postgres.ts

### MEDIUM Passing --force in interactive mode unnecessarily

Wrong:

```bash
electric projects delete proj_abc --force
# Skips confirmation — dangerous in interactive sessions
```

Correct:

```bash
electric projects delete proj_abc
# Prompts for confirmation interactively

# Use --force only in non-interactive / JSON mode
electric projects delete proj_abc --json --force
```

`--force` is required in `--json` mode (no interactive prompt). In interactive
mode, omit it and let the CLI prompt for confirmation.

Source: packages/cli/README.md § JSON Output

## See also

- [auth](../auth/SKILL.md) — Authentication patterns for CI/CD and token management
- [claimable-resources](../claimable-resources/SKILL.md) — No-auth provisioning and claiming flow

For all CRUD operations on workspaces, projects, environments, and services,
run `electric <resource> --help` to see the full command list and options.

## Version

Targets @electric-sql/cli v0.0.8.