@electric-sql/cli/skills/claimable-resources/SKILL.md

CLI for Electric Cloud

---
name: claimable-resources
description: >
  No-auth provisioning flow for Electric Cloud. Create a claimable resource
  without authentication, poll for readiness, then claim it into a workspace.
  Covers the three-step flow (create, status, claim), the two-phase claim
  process (database claim via dashboard link, then service claim via CLI),
  and scripting patterns. Use when building onboarding flows, demos, or
  quick-start experiences that provision resources before the user has an
  account.
type: core
library: electric-cli
library_version: "0.0.8"
sources:
  - "electric-sql/electric:packages/cli/src/commands/claim/create.ts"
  - "electric-sql/electric:packages/cli/src/commands/claim/status.ts"
  - "electric-sql/electric:packages/cli/src/commands/claim/claim.ts"
---

# Electric Cloud CLI — Claimable Resources

Claimable resources let you provision an Electric-backed Postgres database
**without authentication**. The resource is created in a shared pool, and
later claimed into a user's workspace. This enables onboarding flows, demos,
and quick-start experiences where users get a working database before signing up.

## Setup

No authentication needed for the first two steps:

```bash
# 1. Provision a claimable resource (no auth required)
electric claimable create

# 2. Poll until ready
electric claimable status <claim-id>

# 3. Claim into your workspace (requires auth)
electric auth login
electric claimable claim <claim-id>
```

## Core Patterns

### The three-step flow

**Step 1 — Create** (public, no auth):

```bash
CLAIM_ID=$(electric claimable create --quiet)
echo "Claim ID: $CLAIM_ID"
```

This triggers asynchronous provisioning of a Postgres database with Electric
sync pre-configured. The claim ID is the only handle to the resource.

**Step 2 — Poll for readiness** (public, no auth):

```bash
electric claimable status "$CLAIM_ID"
# State: provisioning  → still setting up
# State: ready         → database is provisioned, ready to claim
# State: claimed       → already claimed by someone
# State: error         → provisioning failed
```

In scripts, poll until `ready`:

```bash
while true; do
  STATE=$(electric claimable status "$CLAIM_ID" --quiet)
  if [ "$STATE" = "ready" ]; then break; fi
  if [ "$STATE" = "error" ]; then echo "Failed"; exit 1; fi
  sleep 2
done
```

**Step 3 — Claim** (requires auth):

```bash
# Claim into your workspace
electric claimable claim "$CLAIM_ID"
```

This is a two-phase process:

1. If the database hasn't been claimed yet, the CLI outputs a dashboard URL.
   Visit it to claim the database (this binds it to your account).
2. Once the database is claimed, run `electric claimable claim` again to move
   the service into your workspace, project, and environment.

### Scripting the full flow (JSON mode)

```bash
# Create
CLAIM_ID=$(electric claimable create --json | jq -r '.claimId')

# Wait for provisioning
while true; do
  STATE=$(electric claimable status "$CLAIM_ID" --json | jq -r '.state')
  [ "$STATE" = "ready" ] && break
  [ "$STATE" = "error" ] && { echo "Provisioning failed" >&2; exit 1; }
  sleep 2
done

# Claim (after user has authenticated and visited the claim link)
electric claimable claim "$CLAIM_ID" --json
```

### Specifying a target environment

By default, claiming creates a new project and environment. To claim into an
existing environment:

```bash
electric claimable claim "$CLAIM_ID" --environment env_abc
```

## Common Mistakes

### CRITICAL Trying to claim before the resource is ready

Wrong:

```bash
electric claimable create --quiet
electric claimable claim "$CLAIM_ID"
# Error: Claimable service is not ready (state: provisioning)
```

Correct:

```bash
CLAIM_ID=$(electric claimable create --quiet)
# Wait for provisioning to complete
electric claimable status "$CLAIM_ID"  # Check state is "ready"
electric claimable claim "$CLAIM_ID"
```

Provisioning is asynchronous. Always check status before claiming.

Source: packages/cli/src/commands/claim/claim.ts

### HIGH Expecting claim to complete in one step

Wrong:

```bash
electric claimable claim "$CLAIM_ID"
# Output: "Visit the link below to claim the database: https://..."
# Agent assumes the claim is done — it's not
```

Correct:

```bash
electric claimable claim "$CLAIM_ID"
# Output: "Visit the link below to claim the database: https://..."
# → User visits the URL in browser to bind the database to their account
# Then run claim again:
electric claimable claim "$CLAIM_ID"
# Output: "Source claimed successfully." with service details
```

The claim is a two-phase process. The first call returns a dashboard URL if
the database hasn't been bound to an account yet. The second call (after the
user visits the URL) moves the service into their workspace.

Source: packages/cli/src/commands/claim/claim.ts

### MEDIUM Losing the claim ID

Wrong:

```bash
electric claimable create
# Output: Claim ID: clm_abc123
# ... forgot to save it, no way to recover
```

Correct:

```bash
CLAIM_ID=$(electric claimable create --quiet)
echo "$CLAIM_ID" >> .claimable-ids  # Persist for later
```

The claim ID is the only handle to the provisioned resource. If lost, the
resource cannot be claimed or tracked. Always capture it in scripts.

Source: packages/cli/src/commands/claim/create.ts

## See also

- [getting-started](../getting-started/SKILL.md) — Standard (authenticated) setup flow
- [auth](../auth/SKILL.md) — Authentication required for the claim step

For command details, run `electric claimable --help`.

## Version

Targets @electric-sql/cli v0.0.8.