Instances with surreal cloud

This page walks through everyday instance work from the command line: deploying a SurrealDB Earth or dedicated instance, finding it again, opening a SurrealQL session, resizing it, pausing it, taking backups, and deleting it. It assumes you are signed in and that an organisation resolves; see Authentication if not. For every flag on every verb, see the surreal cloud reference.

Before you start

Instances belong to an organisation, and there is no route that lists them across organisations. Pick one for the profile once, and every instance command follows it.

surreal cloud org use acme

--org overrides it for a single command, and SURREAL_CLOUD_ORG overrides it for a shell. See Organisations for the full order of precedence.

The catalogues tell you what you can deploy.

surreal cloud catalog residencies
surreal cloud catalog regions
surreal cloud catalog instance-types
surreal cloud catalog instance-versions
surreal cloud catalog storage-types
surreal cloud org plans

catalog residencies lists where an Earth instance can keep its data. The other catalogues are for dedicated instances. catalog lists what the platform offers in general. org plans is narrower and organisation-specific - it is the one to trust before deploying a dedicated instance.

Create an instance

surreal cloud instance deploy [OPTIONS] [NAME]

create is an alias of deploy. --region decides what is deployed: with no --region, or --region earth, you get a SurrealDB Earth instance, and with a cloud region you get a dedicated instance there. At a terminal, deploy asks for anything you did not pass as a flag, starting from the same defaults as the deploy page in SurrealDB Studio, and asks you to confirm before it deploys. --yes, or a script that cannot prompt, takes every default.

An Earth instance

surreal cloud instance deploy edge-api
surreal cloud instance deploy edge-api --residency eu --cells 10 --yes

An Earth instance takes Earth's own settings, which are the same as on the deploy page: a data residency, a preferred location, the number of cells, a network policy and capabilities. It always runs the platform's latest SurrealDB.

A dedicated instance

surreal cloud instance estimate --type shared-1 --region aws-euw1
surreal cloud instance deploy production --region aws-euw1 --nodes 1 --type shared-1

Price a dedicated instance first if the cost matters, then deploy it. A dedicated instance takes a node count, an instance type for it, a version, storage and an access type.

A flag for the other kind of instance is refused rather than ignored, so --cells with a cloud region, or --nodes without one, stops the command before anything is deployed.

deploy waits until the instance is ready before it returns, so the next line in your script can connect. Pass --no-wait to return as soon as the API accepts the request; the output then includes the surreal cloud instance watch command to pick the state back up.

Naming an instance

Every command that takes an instance accepts four spellings: the id, the slug, the name, or org/name when you want to be explicit about which organisation.

surreal cloud instance get production
surreal cloud instance get acme/production
surreal cloud instance get prod-a1b2c3

Omit the name at a terminal and surreal cloud offers a picker. Omit it in a script and you get a usage error that lists the available instances, so the failure tells you what you should have typed.

Find instances

surreal cloud instance list
surreal cloud instance list --wide
surreal cloud instance list --columns name,state,version --sort name
surreal cloud instance get production

--columns, --wide, --sort, --reverse, and --limit shape the table. The API has no pagination or sort parameter, so all five are applied on your machine after the whole list arrives - and none of them reaches --json, where the complete payload is always emitted. A --limit 1 must not silently truncate a pipeline.

Connect to an instance

surreal cloud instance endpoint production
surreal cloud instance sql production --namespace app --database main

instance endpoint prints the endpoint alone, with no label and no styling, and its output is byte-identical whether you are at a terminal or in a pipe. That makes $(surreal cloud instance endpoint production) safe to embed in another command.

instance sql resolves the instance, mints a database token, and hands over to surreal db sql through the launcher. If the database component is not installed, the launcher offers to install it; see Components. Everything after -- is passed to surreal db sql verbatim, so the full flag surface of the database shell is available. The token travels in the child process's environment, never in argv, where ps and shell history can both read it.

instance import and instance export work the same way. All three need a namespace and a database, because surreal db requires them. The check happens before a token is minted.

surreal cloud instance export production --namespace app --database main -- backup.surql
surreal cloud instance import staging --namespace app --database main -- seed.surql

To authenticate your own client instead, mint a database token.

surreal cloud instance token production > token.txt
surreal cloud instance jwks production

instance token refuses to print to a terminal, where the token would stay in your scrollback. Pipe it, redirect it, or pass --reveal if you meant to read it. instance jwks fetches the key set that verifies those tokens; under --json it emits the whole key set so it can be piped straight into a verifier.

Scale an instance

surreal cloud instance update production --compute-units 4
surreal cloud instance update production --storage 100
surreal cloud instance update production --version 3.2.4

Pass at least one of --type, --compute-units, --storage, --version, or --access-type. With no flags at all, update is a usage error rather than a silent no-op.

One invocation may be several requests. Each field has its own route, and surreal cloud applies them in a fixed order - type, compute units, storage, version, access type - stopping at the first failure. If a later change fails, the earlier ones have already been applied.

An Earth instance has no type, compute units, storage size or version choice, so update refuses those flags for one. It takes --name instead, which renames an Earth instance without restarting it:

surreal cloud instance update edge-api --name edge-api-eu

The number of cells is changed through the Cloud API with surreal cloud api, as Choose a cell count shows.

Pause and resume

surreal cloud instance pause staging
surreal cloud instance resume staging

Pausing stops compute charges and keeps storage and configuration. Pausing an instance that is already paused prints a note, still emits the same document, and exits 0, so a script that pauses an environment every evening is safe to run twice.

Watch an operation

instance watch follows an operation that was started elsewhere - by a colleague, by Studio, or by an earlier --no-wait command.

surreal cloud instance watch production
surreal cloud instance watch production --until paused
surreal cloud instance watch production --json

--until takes ready, paused, or deleted. Under --json, watch writes one compact object per line to stdout as the state changes, because the transitions are the answer rather than a progress report.

Waiting semantics

deploy, update, delete, pause, and resume wait for the instance to settle before they return.

Waiting is on in rich, plain, CI, and --json output alike. A default that changed with the terminal would mean CI changed behaviour rather than presentation, and would break the obvious script: create, then connect.

Polling backs off - two seconds for the first thirty, then five, then ten - with jitter so parallel waiters do not all poll at the same moment. Being rate limited extends the deadline rather than consuming it, up to a couple of minutes of credit, so a busy account does not get spurious timeouts.

If the wait gives up, surreal cloud exits 10 and says so. That is a distinct outcome from a failure: the operation is still running server-side. Poll again with instance get or instance watch rather than rolling back.

Interrupting a wait does not stop the operation either. It carries on, and surreal cloud instance watch <name> picks the state back up.

Read state, logs, and metrics

surreal cloud instance status production
surreal cloud instance logs production --level error --limit 100
surreal cloud instance logs production --follow
surreal cloud instance metrics production --metric cpu --from 2026-08-11T10:00:00Z
surreal cloud instance usage production

instance status reports the deployment phase and the snapshots the instance can be restored from, as one document.

--level is a display filter applied on your machine - the API has no level parameter - so --json still carries every line the API sent, and a note tells you how many lines were hidden. --follow polls every five seconds and, under --json, writes one compact object per new line.

--metric is free-form, because the set of metrics is not published anywhere surreal cloud can read. cpu, memory, and disk are the usual ones. --from and --to take RFC 3339 timestamps and are forwarded byte for byte.

Earth instances have no metrics or logs, so metrics and logs refuse one. instance usage reports an Earth instance's request units, active time, requests, records read and written, and storage for the billing period so far; see What is measured.

For the equivalent views in the browser, see Monitoring.

Backups

surreal cloud instance backup list production
surreal cloud instance backup create production
surreal cloud instance backup policy get production
surreal cloud instance backup policy set production --daily 14 --weekly 8

The three retention flags - --daily, --weekly, --monthly - take a number of periods to keep, or the literal default to restore your organisation's own value for that tier. --frequency-hours sets how often a snapshot is taken, in whole hours up to 24; the plan decides which values are allowed.

Only a reduction asks for confirmation. Lengthening a retention cannot lose a snapshot, so it is applied without a prompt.

Which tiers you may change depends on the organisation's plan. backup policy get shows which are editable.

instance backup create returns as soon as the platform accepts the request. It has no --wait, and a new snapshot takes a while to appear in the list, so do not expect to restore from one you took a moment ago.

Restoring means creating a new instance from a snapshot, which leaves the original untouched.

snapshot=$(surreal cloud instance backup list production --json \
  | jq -r 'sort_by(.started_at) | last | .snapshot_id')

surreal cloud instance create recovery \
  --type shared-1 --region aws-euw1 \
  --restore-from "production/${snapshot}"

See Backups and recovery for retention behaviour and what a snapshot contains. Earth instances have no backups or snapshots, so the backup commands refuse one.

Capabilities

Capabilities decide what SurrealQL running on the instance may do: scripting, guest access, outbound network access, which functions and RPC methods are permitted.

surreal cloud instance capabilities get production
surreal cloud instance capabilities set production --deny-scripting --allow-net api.example.com

The endpoint is a full replacement, so capabilities set reads the current configuration, applies your flags, prints what would change, and asks before writing. Two consequences matter:

• •

  A list flag replaces that list. --allow-net a.example.com,b.example.com sets the whole list. A later run naming only a.example.com removes b.example.com.

• •

  Anything you do not name is left exactly as it is, including capabilities this version of surreal cloud does not know about.

Flags that would change nothing print a note and write nothing. --force skips the confirmation.

For what each capability means, see Configure an instance and Network access.

Network policy

A network policy lists the client addresses that may connect to an Earth instance, as IP addresses or CIDR blocks. A dedicated instance has none; its access is set with update --access-type.

surreal cloud instance network get edge-api
surreal cloud instance network set edge-api --allow-ip 203.0.113.0/24
surreal cloud instance network set edge-api --open

network set works like capabilities set: it replaces only the lists you name, shows what would change, and asks before writing. A denied address stays denied even when the allow list matches it, and --open clears both lists to admit every address again. See Limit the addresses that can connect.

Delete an instance

surreal cloud instance delete staging
surreal cloud instance delete staging --force

The confirmation names the instance, its slug, and its region. Declining changes nothing and exits 0. --force skips the prompt; in an unattended session with neither --force nor --yes, delete exits 2 having sent no request.

Deletion removes the instance and everything in it. Take an export or confirm a snapshot first.

Worked examples

Stand up a review environment

#!/usr/bin/env bash
set -euo pipefail

name="review-${1}"

surreal cloud instance create "$name" --type shared-1 --region aws-euw1
surreal cloud instance import "$name" --namespace app --database main -- fixtures/seed.surql
surreal cloud instance endpoint "$name"

create returns only once the instance is ready, so the import on the next line has something to talk to. The final line prints the endpoint for whatever consumes this script.

Pause every non-production instance overnight

#!/usr/bin/env bash
set -euo pipefail

surreal cloud instance list --json \
  | jq -r '.[] | select(.state == "ready" and .name != "production") | .name' \
  | while read -r name; do
        surreal cloud instance pause "$name" --wait-timeout 5m
    done

Clone production from its latest snapshot

#!/usr/bin/env bash
set -euo pipefail

snapshot=$(surreal cloud instance backup list production --json \
  | jq -r 'sort_by(.started_at) | last | .snapshot_id')

surreal cloud instance create scratch \
  --type shared-1 --region aws-euw1 \
  --restore-from "production/${snapshot}"

surreal cloud instance endpoint scratch

Next steps

• •

  Organisations - members, roles, invitations, usage, and spend.

• •

  Scripting - exit codes and the --json contract in full.

• •

  surreal cloud reference - every instance flag and default.