# surrealctl

The control-plane CLI: what surrealctl does, when to reach for it instead of SurrealDB Studio or the surreal binary, and a sixty-second quickstart.

`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](/docs/reference/cli/surrealctl/overview.md).

## Control plane and data plane

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

| Tool | Plane | Answers |
| --- | --- | --- |
| `surrealctl` | Control plane | Which instances exist, what they run, what they cost, who may reach them |
| [`surreal`](/docs/reference/cli/surrealdb-cli/overview.md) | Data plane | Queries, imports, exports, and running a server yourself |

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](https://app.surrealdb.com)** — 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.

```bash title="First session"
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](/docs/manage/surrealctl/install.md).

## 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.

```bash title="Machine-readable output"
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](/docs/manage/surrealctl/scripting.md) for the full contract.

## Command groups

| Group | What it manages |
| --- | --- |
| `auth` | Sign in, sign out, and inspect credentials |
| `org` | Organisations, roles, usage, and spend |
| `instance` | Instances: lifecycle, endpoints, logs, metrics, capabilities, backups |
| `team` | Organisation members |
| `invite` | Organisation invitations |
| `token` | Personal access tokens |
| `catalog` | Regions, instance types, and SurrealDB versions the platform offers |
| `spectron` | Spectron contexts, keys, and principals |
| `config` | Configuration stored on this machine |
| `context` | Profiles, and which one is in force |
| `api` | Call the API directly |
| `open` | Open a dashboard page in a browser |
| `status` | Check that everything is configured and reachable |

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](/docs/manage/surrealctl/install.md) — get the binary, sign in, and confirm the setup.
- [Authentication](/docs/manage/surrealctl/authentication.md) — login sessions, personal access tokens, and where credentials live.
- [Instances](/docs/manage/surrealctl/instances.md) — create, connect, scale, pause, back up, and delete.
- [Organisations](/docs/manage/surrealctl/organisations.md) — members, roles, invitations, tokens, usage, and spend.
- [Scripting](/docs/manage/surrealctl/scripting.md) — `--json`, exit codes, and unattended runs.
- [`surrealctl` reference](/docs/reference/cli/surrealctl/overview.md) — every command, flag, and default.