# SnoutData Cloud, for an agent One page with every command, every flag, the output shapes, and the refusals. If you are a model reading this to provision a database, you need nothing else. :::note The `snoutdata` CLI is on npm. `npx snoutdata` downloads one bundled file with no dependencies and needs Node 20 or newer. ::: ## The whole thing in two commands ```bash export SNOUTDATA_ACCESS_TOKEN=sdt_... # made once, by a person, with `snoutdata tokens create` npx snoutdata init --env --json ``` That creates a hosted Postgres database, waits until it is actually serving, writes `.snoutdata/project.json` and `.env`, and leaves `DATABASE_URL` in place. It is idempotent: run it again in the same folder and you get the same project, not a second one. A run holding nothing but an access token, with no browser and no human, has been driven end to end in 21 seconds. ## The contract | | | | --- | --- | | `--json` | Accepted on every command. **Exactly one JSON value on stdout and nothing else.** Progress, warnings and prose go to stderr, so piping into `jq` needs no filtering. | | No prompts | Nothing asks a question when stdin is not a terminal. A command that would have to ask names the flag to pass and exits 2. | | Unknown flags | An error, never ignored. A typo stops the command instead of quietly doing something else. | | Idempotence | `init` reuses a linked project. `db export` treats a second request while one is running as the same request. `tokens revoke` on an already revoked token reports `changed: false` rather than failing. | ### Exit codes | Code | Meaning | What to do | | --- | --- | --- | | `0` | Fine. | Continue. | | `1` | The operation failed. | Read the message on stderr. Do not retry blindly. | | `2` | The command was wrong. | Fix the arguments. Retrying identically will fail identically. | | `3` | The credential is no good: never signed in, expired, or revoked. The message says which. | Ask a human for a new access token. | | `4` | Not ready yet. | Retry with a delay. | | `127` | `psql`, or `pg_restore` for an archive, is not installed. | Install it, or use a path that does not need it. | ### Where the credential comes from 1. `SNOUTDATA_ACCESS_TOKEN` 2. `~/.snoutdata/auth.json`, written by `snoutdata login` The environment wins deliberately. Two kinds of credential go in that variable: | | Lasts | Use it for | | --- | --- | --- | | A session, written by `login` | one hour, refreshed automatically | a person at a terminal | | An `sdt_…` access token | does not expire unless asked to; revocable | CI, cron, an agent | The control plane exchanges an `sdt_` token for a short-lived JWT on its side, so row-level security in the database is still the only thing deciding what it can see. **A token cannot create another token.** A token can revoke itself, or any other. ### Where the project comes from 1. `--ref` 2. `SNOUTDATA_PROJECT` 3. `.snoutdata/project.json` in this folder **or any parent**, walked upward the way git finds `.git` A command that needs a project and cannot find one exits 2 saying so. ## Every command | Command | Flags | | --- | --- | | `snoutdata init` | `--name NAME` `--region REGION` `--env` `--ref REF` | | `snoutdata login` | `--provider github` (default `google`) | | `snoutdata logout` | | | `snoutdata whoami` | | | `snoutdata tokens list` | | | `snoutdata tokens create` | `--name NAME` (required) `--expires DAYS` | | `snoutdata tokens revoke ` | | | `snoutdata projects list` | | | `snoutdata projects create` | `--name NAME` (required) `--region REGION` `--team NAME\|ID` `--no-wait` | | `snoutdata projects pause` | `--ref REF` | | `snoutdata projects resume` | `--ref REF` | | `snoutdata projects delete` | `--ref REF` | | `snoutdata teams` | | | `snoutdata link` | `--ref REF` (required) | | `snoutdata usage` | `--ref REF` `--days N` (default 30, max 365) `--history` | | `snoutdata db url` | `--ref REF` | | `snoutdata db psql` | `--ref REF` `-- PSQL ARGS...` | | `snoutdata db reset-password` | `--ref REF` | | `snoutdata db export` | `--ref REF` `--out FILE` `--status` | | `snoutdata db push` | `--dir DIR` (default `migrations`) `--dry-run` `--out-of-order` | | `snoutdata db restore` | `--file DUMP` (required) `--ref REF` `--force` | | `snoutdata mcp` | `--allow-delete` | Global on every command: `--json`, `--help`, `--version`. ## What each command answers ### `init` ```bash npx snoutdata init --name analytics --env ``` Human output, on stderr: ``` Creating a project called "analytics"… Created x8x3sb2hcx4xn. Waiting for it to start… creating ready Ready. x8x3sb2hcx4xn in us-west-2. The password is stored for you: `snoutdata db url` prints this again. Wrote DATABASE_URL in /work/analytics/.env. ``` The connection URL is the one thing on stdout. With `--json` you get the project, its password and the URI as one object. ### `whoami` ```json { "id": "9f3a…", "email": "you@example.com", "via": "token", "token": { "id": "…", "name": "ci", "prefix": "sdt_wgygjk2r" } } ``` `via` is `"jwt"` for a session and `"token"` for an access token. `token` is `null` for a session. ### `projects list` ``` REF NAME STATE REGION LAST CONNECTION x8x3sb2hcx4xn first light ready us-west-2 2 hours ago ztwxsybkhpfee scratch paused us-west-2 9 days ago ``` A project over its storage limit shows `read-only` in the STATE column rather than `ready`, because that is the state that matters to whoever reads it. With `--json`: ```json { "projects": [ { "ref": "x8x3sb2hcx4xn", "name": "first light", "region": "us-west-2", "production": false, "desiredState": "running", "state": "ready", "stateDetail": null, "wakesInstantly": true, "sizeBytes": 8074035, "readOnly": false, "readOnlyPending": false, "readOnlySince": null, "host": "x8x3sb2hcx4xn.db.snoutdata.com", "database": "x8x3sb2hcx4xn", "user": "x8x3sb2hcx4xn_owner", "createdAt": "2026-09-04T11:02:19.417Z", "lastConnectionAt": "2026-09-06T09:41:00.000Z", "pausedAt": null } ], "allowance": { "tier": "plus", "used": 1, "maxProjects": 5, "maxStorageBytes": 8589934592, "mayCreate": true } } ``` **`state` and `desiredState` do not share a vocabulary.** The settled form of a desired `running` is a state of `ready`. Poll `state`, not `desiredState`. ### `db url` Exactly one line on stdout, and it contains a live password: ``` postgres://x8x3sb2hcx4xn_owner:…@x8x3sb2hcx4xn.db.snoutdata.com:5432/x8x3sb2hcx4xn?sslmode=require ``` With `--json`: `ref`, `host`, `port`, `database`, `user`, `password`, `ssl`, `uri`, `wakesInstantly`, `state`. If the project is over its storage limit, a warning goes to **stderr**, never stdout, so it cannot end up inside a `.env` line. ### `usage` ``` first light (x8x3sb2hcx4xn) 7.7 MB of 8.0 GB on plus (0%). Over 2 days: 1d 6h of compute, 2 connections. ``` With `--history`, the day-by-day table underneath: ``` DAY SIZE BACKUPS COMPUTE CONNS 2026-09-04 7.5 MB 41.2 MB 24h 1 2026-09-05 7.7 MB 41.9 MB 24h 1 2026-09-06 - - none 0 ``` **A dash is a day nothing measured it**, which is what a paused project looks like. It is not zero. The current size is the most recent day that has a reading; compute and connections are summed, because there a missing day really did have none. With `--json` the answer carries `ref`, `name`, `readOnly`, `measuredAt`, the `days` array (`day`, `dbBytes`, `repoBytes`, `computeSeconds`, `connections`, with `dbBytes` and `repoBytes` `null` on an unmeasured day), the `limit` (`tier`, `maxStorageBytes`), and a `summary` (`days`, `latest`, `peakDbBytes`, `computeSeconds`, `connections`, `storage`). `summary.storage.state` is `"ok"`, `"near"` (at or above 80%) or `"over"`. That is the field to branch on. ### `tokens` ``` PREFIX NAME STATE LAST USED EXPIRES sdt_wgygjk2r ci live 3 hours ago never sdt_4b1qz8mt laptop revoked 2 months ago 2026-12-04 ``` `tokens create` prints the token on stdout, alone, so this is correct with no filtering: ```bash SNOUTDATA_ACCESS_TOKEN=$(npx snoutdata tokens create --name ci) ``` It is shown once. Only its hash is stored. ### `teams` ``` NAME ID SHARE SolarPanda 2f0c9d1e-2b4a-4a77-9d1e-1c0a5b7d3f21 yes ``` A team you can see but cannot share into is listed with the reason in the SHARE column rather than hidden, because "your team is missing" sends somebody looking for a bug. ### `db push` ```bash npx snoutdata db push --dry-run npx snoutdata db push ``` Runs every `.sql` file in the folder, in byte-wise name order, once each, recording what ran in a `_snoutdata_migrations` table in the project's own database. Order is `ls | sort`, so zero-pad (`001-`, `002-`) or `10-` sorts before `9-`. The ledger row is written in the same transaction as the migration, so a file that fails half way leaves nothing behind. A file that cannot be wrapped declares it: ```sql -- snoutdata:no-transaction create index concurrently people_email_idx on people (email); ``` Such a file gets no ledger row until it finishes, so an interrupted one runs again and has to tolerate that. `db push` says so before it runs one. It refuses three things, reports every problem at once, and overrides only one: | Refusal | Override | | --- | --- | | A file that changed since it ran | none | | A file that has gone (usually a rename, which is how the same SQL runs twice) | none | | A new file that sorts before one already applied | `--out-of-order` | Needs `psql`: a migration connects like any other client, because the control plane's SQL endpoint refuses DDL. ### `db export` and `db restore` ```bash npx snoutdata db export --out dump.sql # take a copy and download it npx snoutdata db export --status # look, without starting one npx snoutdata db restore --file dump.sql ``` `--status` exists so you can look without asking, because the other branch runs a `pg_dump` against a live database. A missing download link is not a failed export: links are signed with credentials that rotate every few hours, and asking again signs a fresh one against the same dump. `db restore` sniffs the format from the file's first bytes rather than its name. It refuses a database that already has tables (`--force` overrides) and a project over its storage limit (`--force` does not). Errors about not owning `pg_stat_statements` when restoring one of our own exports are expected, are named as such, and do not fail the command. ## MCP server ```bash npx snoutdata mcp [--allow-delete] ``` An MCP server on stdin and stdout, speaking protocol version `2024-11-05`. In a Claude Code MCP config: ```json { "mcpServers": { "snoutdata": { "command": "npx", "args": ["snoutdata", "mcp"] } } } ``` It holds **no credential of its own**. It runs as whoever started it and every call is the same function the CLI makes, so it is exactly as capable as that person, minus deleting a database. ### The eight tools | Tool | Arguments | Does | | --- | --- | --- | | `whoami` | | Who this is signed in as, and how. | | `list_projects` | | Every database on the account, with ref, name, region, state, size, and whether it is read-only. | | `create_project` | `name` (required), `region`, `teamId` | Makes a database and waits for it to be ready. | | `get_connection_url` | `ref` (required) | The `postgres://` URL. **It contains a live password.** | | `pause_project` | `ref` (required) | Stops a project. Its data is kept and the next connection wakes it. | | `resume_project` | `ref` (required) | Starts a paused project without waiting for a connection. | | `push_migrations` | `ref` (required), `dir`, `dryRun` | Runs the `.sql` files in a folder. Needs `psql`. | | `delete_project` | `ref` (required) | **Destroys a database.** Off unless `--allow-delete`. | ### Three things about it that will otherwise surprise you **The tool list is fixed at connect.** MCP clients read `tools/list` once, so nothing is registered conditionally on state. **`delete_project` is listed even when it is off**, and answers with a sentence about `--allow-delete`. A tool that is merely absent gets worked around with something invented; one that is present and says no can be reported back to the user. **A refusal is a result, not a protocol error.** A quota, a paused project or a disabled tool comes back as a successful call with `isError` and a sentence, because a JSON-RPC error reads as "this tool is unusable" and stalls a client. ### It does not run SQL Deliberately. `snoutdata sql` does not exist yet, and when it does it will go through the engine's guard. An unguarded statement runner in an agent's hands is the thing that guard exists to prevent. An agent that wants to query calls `get_connection_url` and uses a real Postgres client. ## Refusals you should expect, and what they mean | You will see | Because | What to do | | --- | --- | --- | | The plan allowance is used up | Free 1 project, Plus 2, Pro 5 | Delete one, or tell the user to change plan | | A free project cannot be marked production | A free project pauses after a week idle; Plus and Pro never pause | Tell the user | | Writes are refused, reads work | Over the plan's storage limit, so the database is read-only | Shrink it, or tell the user to change plan | | Connecting takes a few seconds | The project was paused and the connection is waking it | Wait. It is not an error | | `psql is not installed` (exit 127) | `db psql`, `db push` and `db restore` need it | Use `db url` and a client you have | ## What does not exist Do not invent these: - `snoutdata sql` - Branches, read replicas, larger compute sizes - Scoping an access token to particular projects - Any region other than `us-west-2` The REST and GraphQL data API DOES exist, on paid plans only. A free project is refused it with a sentence about the plan. Auth, storage, realtime and edge functions are on every plan. ## Also read - [Limits, and what is not built](https://docs.snoutdata.com/cloud/limits), which carries what pauses, what a plan gets, what is measured, and what is not protected against. - [CLI reference](https://docs.snoutdata.com/cloud/cli), the same commands written for a person.