> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# surreal cloud reference

What surreal cloud is, where the control plane ends and the database commands begin, how it relates to the former surrealctl, the command grammar, and how this reference is organised.

`surreal cloud` is the component of the [`surreal` launcher](/docs/reference/cli/launcher.md) that manages SurrealDB Cloud from the command line. It is the control plane: it creates and scales instances, reads logs and metrics, manages organisation members and invitations, and mints credentials, all through the SurrealDB API at `https://api.surrealdb.com`.

This reference is for operators, CI pipelines and agents. Every command emits machine-readable JSON on request, keeps its data payload on stdout, and returns an exit code precise enough to branch on.

For installing the launcher, see [Install](/docs/explore/cli/install.md). The launcher offers to fetch `surreal cloud` the first time you run it, or you can install it ahead of time with `surreal install cloud`. For a first walkthrough, see the [guide](/docs/explore/cli/cloud.md).

## Coming from surrealctl

`surreal cloud` was previously the standalone `surrealctl` tool. The commands and flags are the same, so a script written for `surrealctl` works after replacing the program name with `surreal cloud`. Two things migrate automatically:

- **Configuration and login.** On its first run, `surreal cloud` copies your configuration and stored login from `~/.config/surrealctl` (`%APPDATA%\surrealctl` on Windows) to `~/.surrealdb/cloud`. The original is left in place, and from then on the two are independent.
- **Environment variables.** `SURREALCTL_*` variables still work as deprecated aliases for their `SURREAL_CLOUD_*` replacements. When one is set, a single warning on stderr lists each old name with its replacement. The new name wins when both are set.

The `--json` contract and the exit codes are unchanged.

## The control plane and the data plane

`surreal cloud` owns the **control plane**: the resources around a database - instances, organisations, members, tokens, capabilities, backups. The database commands, `surreal db ...`, own the **data plane**: queries, imports, exports, and running a server. Both are reached through the same `surreal` launcher, and `surreal cloud` follows the same conventions so you can move between them without relearning anything.

| Task | Command |
| --- | --- |
| Create, scale, pause or delete a Cloud instance | `surreal cloud instance` |
| Read an instance's logs, metrics or usage | `surreal cloud instance` |
| Invite a colleague, change their role | `surreal cloud team`, `surreal cloud invite` |
| Mint a database token or fetch a key set | `surreal cloud instance token`, `surreal cloud instance jwks` |
| Run a SurrealQL query | [`surreal db sql`](/docs/reference/cli/db/commands/sql.md) |
| Run a local server | [`surreal db start`](/docs/reference/cli/db/commands/start.md) |

Three commands cross the boundary. [`instance sql`](/docs/reference/cli/cloud/commands/instance.md#instance-sql), [`instance import`](/docs/reference/cli/cloud/commands/instance.md#instance-import) and [`instance export`](/docs/reference/cli/cloud/commands/instance.md#instance-export) resolve the instance, mint a database token, and hand off to `surreal db sql`, `surreal db import` or `surreal db export` through the launcher rather than reimplementing SurrealQL. Everything after a `--` separator is forwarded to the database command verbatim.

`surreal cloud` never installs or locates the database itself. The launcher does, and it offers to install the database if it is missing. Run on its own, outside the launcher, the three handoff commands refuse and say how to run them. See [Components](/docs/explore/cli/components.md) for how the launcher runs them.

## Command grammar

The grammar is regular, so it only has to be learned once:

- **Groups are singular nouns.** `instance`, not `instances` - the plural is a visible alias.
- **Verbs are `list`, `get`, `create`, `update`, `delete`.** The only aliases are `ls` for `list` and `rm` for `delete`.
- **Destructive commands take `--force`**, never `--skip-confirmations`. The global `--yes` pre-answers every confirmation in one invocation.
- **`--json` is the only encoding switch.** There is no `--format`.
- **Two deliberate exceptions**, both in `team`: `team remove` ends a membership rather than deleting a person, and `team invite` sends an invitation, which no house verb covers.

Any noun group invoked on its own prints its own help, and `help` works at every level:

```bash
surreal cloud instance
surreal cloud help instance create
```

## How this reference is organised

The cross-cutting pages describe behaviour shared by every command. Read them once.

| Page | Covers |
| --- | --- |
| [Authentication](/docs/reference/cli/cloud/authentication.md) | Login sessions, personal access tokens, and where credentials are stored |
| [Global flags](/docs/reference/cli/cloud/global-flags.md) | The 16 flags every command accepts, their environment variables, and the precedence chain |
| [Output and exit codes](/docs/reference/cli/cloud/output-and-exit-codes.md) | The `--json` contract, the stream split, list presentation flags, and every exit code |
| [Long-running operations](/docs/reference/cli/cloud/long-running-operations.md) | `--wait`, `--no-wait`, polling behaviour, and exit code `10` |

The command pages document every flag, argument and refusal, one page per group. The [commands index](/docs/reference/cli/cloud/commands.md) lists every command:

| Group | Purpose |
| --- | --- |
| [`auth`](/docs/reference/cli/cloud/commands/auth.md) | Sign in, sign out, and inspect credentials |
| [`org`](/docs/reference/cli/cloud/commands/org.md) | Manage organisations, roles, usage and spend |
| [`instance`](/docs/reference/cli/cloud/commands/instance.md) | Manage instances, capabilities and backups |
| [`team`](/docs/reference/cli/cloud/commands/team.md) | Manage organisation members |
| [`invite`](/docs/reference/cli/cloud/commands/invite.md) | Manage organisation invitations |
| [`token`](/docs/reference/cli/cloud/commands/token.md) | Manage personal access tokens |
| [`catalog`](/docs/reference/cli/cloud/commands/catalog.md) | Browse the platform catalogues |
| [`config`](/docs/reference/cli/cloud/commands/config.md) | Read and write configuration |
| [`context`](/docs/reference/cli/cloud/commands/context.md) | Inspect and switch profiles |
| [`whoami`, `api`, `open`, `status`, `version`, `completion`](/docs/reference/cli/cloud/commands/misc.md) | Identity, the raw API escape hatch, and diagnostics |

## Reference syntax

Usage blocks in this reference use one notation throughout:

| Notation | Meaning |
| --- | --- |
| `<NAME>` | A required value you supply |
| `[NAME]` | An optional value you supply |
| `[OPTIONS]` | Zero or more flags |
| `...` | The preceding item may be repeated |
| `--` | Everything after this separator is passed to another program |

Usage blocks are notation, not commands - they carry brackets a shell will not accept. Copy from the examples instead.

## Resource references

Most commands accept a resource by more than one spelling. An organisation is named by id or name. An instance is named by id, slug, name, or `org/name`. A bare id is used without a lookup; anything else is resolved against the organisation in force, and an unrecognised name is answered with a did-you-mean list.

Omit the reference entirely and, on a terminal, the command offers an interactive picker. In a non-interactive session it exits `2` and lists what was available, so a CI failure names the fix.

```bash
surreal cloud instance get production
surreal cloud instance get acme/production
surreal cloud instance get 67upif0m8sh1cn1p2c8t
```