surreal cloud is the component of the surreal launcher 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. 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.
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 cloudcopies your configuration and stored login from~/.config/surrealctl(%APPDATA%\surrealctlon 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 theirSURREAL_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 |
| Run a local server | surreal db start |
Three commands cross the boundary. instance sql, instance import and 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 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, notinstances- the plural is a visible alias.Verbs are
list,get,create,update,delete. The only aliases arelsforlistandrmfordelete.Destructive commands take
--force, never--skip-confirmations. The global--yespre-answers every confirmation in one invocation.--jsonis the only encoding switch. There is no--format.Two deliberate exceptions, both in
team:team removeends a membership rather than deleting a person, andteam invitesends an invitation, which no house verb covers.
Any noun group invoked on its own prints its own help, and help works at every level:
surreal cloud instance
surreal cloud help instance createHow this reference is organised
The cross-cutting pages describe behaviour shared by every command. Read them once.
| Page | Covers |
|---|---|
| Authentication | Login sessions, personal access tokens, and where credentials are stored |
| Global flags | The 16 flags every command accepts, their environment variables, and the precedence chain |
| Output and exit codes | The --json contract, the stream split, list presentation flags, and every exit code |
| Long-running operations | --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 lists every command:
| Group | Purpose |
|---|---|
auth | Sign in, sign out, and inspect credentials |
org | Manage organisations, roles, usage and spend |
instance | Manage instances, capabilities and backups |
team | Manage organisation members |
invite | Manage organisation invitations |
token | Manage personal access tokens |
catalog | Browse the platform catalogues |
config | Read and write configuration |
context | Inspect and switch profiles |
whoami, api, open, status, version, completion | 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.
surreal cloud instance get production
surreal cloud instance get acme/production
surreal cloud instance get 67upif0m8sh1cn1p2c8t