surrealctl

surrealctl is the command-line interface for the SurrealDB Cloud control plane. Use it to sign in, create and list instances, scale them, pause and resume them, read logs and metrics, manage organisation members, and mint tokens — from a terminal, a shell script, or a CI job.

This page covers what the tool is for and gets you through a first session. It is written for operators and developers who already have a SurrealDB Cloud account. For exhaustive flag detail, see the surrealctl reference.

Control plane and data plane

SurrealDB ships two command-line tools, and they divide along a clear line.

The two are siblings, not competitors. surrealctl never speaks SurrealQL. When you run surrealctl instance sql, it resolves the instance, mints a database token, and hands off to the surreal binary — the same binary you would run by hand, with the endpoint and credentials already filled in. The same applies to surrealctl instance import and surrealctl instance export.

That is the whole boundary. Three commands cross it; nothing else needs surreal.

When to use which tool

• •

  SurrealDB Studio — sign-up, browsing data, billing pages, and anything you do once. The browser is the fastest route for one-off work.

• •

  surrealctl — anything you want to repeat, script, schedule, or review in a pull request. Provisioning, scaling, pausing an environment overnight, pulling logs into a report, granting a colleague a role.

• •

  surreal — schema, queries, and data. Also a local server for development.

surrealctl and Studio talk to the same API, so a change made in one shows up in the other.

Sixty-second quickstart

Install the binary, then sign in and deploy something.

surrealctl auth login
surrealctl whoami
surrealctl org list
surrealctl org use acme

surrealctl instance create api --type shared-1 --region aws-euw1
surrealctl instance sql api -- --ns app --db main
surrealctl instance pause api
surrealctl instance delete api --force

auth login opens a browser and stores the session for later commands. org use remembers an organisation so you do not have to name it every time. instance create waits until the instance is ready before it returns, so the sql command on the next line connects to a running database.

For installation instructions, see Install.

Output that scripts can read

Every command that returns a document takes --json, and every command sends its data payload to stdout and everything else — progress, prompts, warnings, errors — to stderr.

surrealctl instance list --json | jq -r '.[] | select(.state == "ready") | .name'

So | jq always works, --json > out.json can still prompt you, and a failed command leaves stdout empty rather than half a document. Exit codes distinguish outcomes a pipeline needs to tell apart: 3 for an expired credential, 5 for a name that does not exist, 10 for a wait that gave up on an operation that is still running.

See Scripting for the full contract.

Command groups

Nouns are singular and verbs are predictable: list, get, create, update, delete. The plural forms are aliases, so surrealctl instances ls works. Only two commands break the pattern, both because the house verb would mislead: team remove ends a membership rather than deleting a person, and team invite sends an invitation.

Deliberate omissions

Three things surrealctl will not do, so you do not go looking for them.

• •

  It does not run queries. instance sql hands off to surreal. A wrapper around SurrealQL would be wrong the first time the language gained a feature.

• •

  There is no sticky current instance. Organisations persist with org use; instances are named on each command or picked interactively. A remembered instance means instance delete in a forgotten terminal tab deletes production.

• •

  It never accepts legal terms on your behalf. surrealctl open terms prints the links and opens them; accepting is something a person does.

Topics

• •

  Install — get the binary, sign in, and confirm the setup.

• •

  Authentication — login sessions, personal access tokens, and where credentials live.

• •

  Instances — create, connect, scale, pause, back up, and delete.

• •

  Organisations — members, roles, invitations, tokens, usage, and spend.

• •

  Scripting — --json, exit codes, and unattended runs.

• •

  surrealctl reference — every command, flag, and default.