surrealctl manages SurrealDB Cloud from the command line. It creates and scales instances, reads logs and metrics, manages organisation members and invitations, mints credentials, and drives Spectron contexts — 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.
The control plane and the data plane
surrealctl owns the control plane: the resources around a database — instances, organisations, members, tokens, capabilities, backups. The surreal CLI owns the data plane: queries, imports, exports, and running a server. The two are siblings, and surrealctl follows the same conventions so you can move between them without relearning anything.
| Task | Tool |
|---|---|
| Create, scale, pause or delete a Cloud instance | surrealctl instance |
| Read an instance's logs, metrics or usage | surrealctl instance |
| Invite a colleague, change their role | surrealctl team, surrealctl invite |
| Mint a database token or fetch a key set | surrealctl instance token, surrealctl instance jwks |
| Run a SurrealQL query | surreal sql |
| Run a local server | surreal start |
Three commands cross the boundary. instance sql, instance import and instance export resolve the instance, mint a database token, and hand off to the surreal binary rather than reimplementing SurrealQL. Everything after a -- separator is forwarded to surreal verbatim. See the surreal handoff for how the binary is located.
Before you start
This reference documents commands and flags. For installing surrealctl, signing in, and a first walkthrough, see the surrealctl guide.
| Task | Page |
|---|---|
| Install the binary and sign in | Install |
| Choose between a login session and a token | Authentication |
| Work through a first instance | Instances |
Command grammar
The grammar is regular, and worth learning 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:
surrealctl instance
surrealctl 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:
| 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 |
spectron | Manage Spectron contexts, keys and principals |
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.
surrealctl instance get production
surrealctl instance get acme/production
surrealctl instance get 67upif0m8sh1cn1p2c8t