@scloudgg/cli

Instant, ephemeral PostgreSQL from your terminal — scloud.gg.

Spin up a real Postgres database in seconds, get a connection string, use it, and throw it away. Perfect for CI, tests, demos, and throwaway dev work. Billed by the minute: 60 free minutes every month, then credits.

Install

npm install -g @scloudgg/cli
# or run without installing:
npx @scloudgg/cli db create

Requires Node.js 18+.

Authenticate

Create an API key at https://scloud.gg/dashboard/settings, then:

scloud login

In CI, skip login and set an environment variable instead:

export SCLOUD_API_KEY=sk_scloud_...

Quick start

# Create a database and wait for it to be ready
scloud db create my-test --wait

# Use it (connection string on stdout, composes cleanly)
export DATABASE_URL=$(scloud db url <id>)
psql "$DATABASE_URL"

# Tear it down
scloud db kill <id>

Commands

| Command | Description | | --- | --- | | scloud login / logout / whoami | Manage authentication | | scloud db create [name] | Provision a database | | scloud db ls | List your databases | | scloud db get <id> | Show database details | | scloud db url <id> | Print the connection string only | | scloud db status <id> | Status + usage | | scloud db kill <id> | Tear down a database | | scloud db keep <id> | Promote to a persistent $1.50/mo database | | scloud credits | Show free minutes + credit balance | | scloud credits buy <pack> | Buy a credit pack (starter pro scale) | | scloud usage | Per-database usage this month |

Useful flags

• --wait — block until the database is ready. Works on db create, db url, db get, and db status (e.g. scloud db url <id> --wait).
• --ttl <duration> — auto-delete after 30m, 2h, 1d, etc. (great for CI — never leak credits).
• --hook <url> — POST the connection details to a URL once the database becomes active (fires ~30–60s after create, when provisioning finishes — not instantly).
• --json — machine-readable output on stdout (every command).

CI example

# GitHub Actions
- run: npm install -g @scloudgg/cli
  env: { SCLOUD_API_KEY: ${{ secrets.SCLOUD_API_KEY }} }
- run: |
    ID=$(scloud db create ci-$GITHUB_RUN_ID --wait --ttl 30m --json | jq -r .id)
    export DATABASE_URL=$(scloud db url "$ID")
    npm test
    scloud db kill "$ID"

The --ttl is a safety net: even if the job crashes before kill, the database self-destructs and stops consuming credits.

Billing

Ephemeral (CLI/API) databases consume 1 credit per minute the database is alive. Every account gets 60 free minutes per month; beyond that, buy credits:

| Pack | Credits | Price | Per minute | | --- | --- | --- | --- | | Starter | 100 | $2.00 | $0.020 | | Pro | 250 | $4.00 | $0.016 | | Scale | 1000 | $12.00 | $0.012 |

Credits never expire. Run scloud credits to check your balance.

Exit codes

0 success · 2 usage/auth error · 3 network error · 4 out of credits · 5 provisioning/timeout.

License

MIT