surreal cloud instance

surreal cloud instance manages instances: the databases themselves. It is the largest group in the CLI, and covers provisioning, scaling, observability, credentials, capabilities and backups. Three of its commands, sql, import and export, run the database through the surreal launcher as surreal db sql, surreal db import and surreal db export.

This group declares the scopes read:cloud and write:cloud-instances. A personal access token is read-only here: the gateway refuses every non-GET Cloud route for one, so the commands that change an instance answer 403 and exit 4 regardless of the token's scopes. See Authentication.

surreal cloud instance <COMMAND> [OPTIONS]surreal cloud instances <COMMAND> [OPTIONS]

Naming an instance

Four spellings are accepted: the id, the slug, the name, or org/name. Only a bare id avoids a lookup against the organisation. A slug always contains a hyphen, so it can never be mistaken for an id.

surreal cloud instance get production
surreal cloud instance get production-6xk2
surreal cloud instance get acme/production
surreal cloud instance get 67upif0m8sh1cn1p2c8t

Omit the reference entirely and, on a terminal, you get a picker. Elsewhere it is a usage error, exit 2, listing what was available:

No instance was given and this session cannot prompt.
Name one, or pass --org to change which organization is searched.

Available:
  production
  staging

There is deliberately no instance use, and no default instance: a sticky implicit target is fine for a noun whose verbs are mostly reads, and wrong for one whose verbs include delete. The organisation searched comes from --org and the precedence chain, and org use can remember one.

Every [INSTANCE] argument below behaves this way: only the organisation is resolved from context, so without an instance argument a command prompts on a terminal and refuses elsewhere.

A command that waits for the instance (create, update, delete, pause, resume and watch) follows the rules in Long-running operations. The waiting default is on, the timeout is 15 minutes, a timeout exits 10, and an instance that enters a failed state exits 6. --wait-timeout takes a duration such as 30s, 10m or 2h, and a bare number is seconds.

surreal cloud instance list

List the instances in an organisation.

surreal cloud instance list [OPTIONS]

This command takes no positional argument, deliberately: a positional here would read as an instance. The organisation comes from --org and the precedence chain.

Accepts the list presentation flags and nothing else. Column ids are name, state, type, version, region, compute_units and storage, with id, slug, host, access_type and organization_id under --wide. An organisation with no instances is a success: exit 0, a note, and an empty array under --json.

surreal cloud instance list

NAME        STATE   TYPE          VERSION  REGION     UNITS  STORAGE
production  ready   production-2  3.2.4    aws-euw1       4   100 GB
staging     paused  shared-1      3.2.4    aws-euw1       1    10 GB

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

surreal cloud instance get

Show one instance.

surreal cloud instance get [OPTIONS] [INSTANCE]

This command has no options of its own.

surreal cloud instance get production

surreal cloud instance get production --json | jq -r .state

The detail view reports the id, slug, state, type, version, region, compute units, storage, access type, endpoint, private host when there is one, and the owning organisation. It adds the storage cool-off when storage cannot be changed yet, the storage backend and backup retention when the platform reports them, and the versions the instance can upgrade to.

surreal cloud instance create

Create an instance.

surreal cloud instance create [OPTIONS] --type <SLUG> --region <SLUG> <NAME>

surreal cloud instance create api --type shared-1 --region aws-euw1

surreal cloud instance create production \
    --type production-2 \
    --region aws-euw1 \
    --compute-units 4 \
    --storage 100

surreal cloud instance create staging \
    --type shared-1 \
    --region aws-euw1 \
    --restore-from production/rsnapshot-20260811-150405

The command prints Creating <name> (<slug>). on stderr as soon as the API accepts the request. With the wait, it then reports progress and emits a fresh detail view of the ready instance. With --no-wait it emits the accepted request and hints at surreal cloud instance watch <name>.

The organisation comes from --org and the precedence chain.

Refusals, all exit 2 and all before any request:

• •

  A name outside 1 to 30 characters, with the length it counted.

• •

  --compute-units below 1 (Compute units start at 1.), or --storage below 1 (Storage starts at 1 GB.).

• •

  A --type or --region that the organisation's plan does not offer. The message suggests the closest match and lists what is available. This check is skipped when the plan lists none.

• •

  A malformed --restore-from, which is split on the last /:

`prod-snap-1` is not a snapshot reference. Use <instance>/<snapshot>, for example
production/rsnapshot-20250128-150405.
Run `surreal cloud instance status <instance>` to list the snapshots an instance can be restored from.

surreal cloud instance update

Change an instance's type, size, or version.

surreal cloud instance update [OPTIONS] [INSTANCE]

There is no single update route on the API - each field has its own - so one invocation is several requests. They are applied in a fixed order and stop at the first failure:

1. 1.

   --type

2. 2.

   --compute-units

3. 3.

   --storage

4. 4.

   --version

5. 5.

   --access-type

surreal cloud instance update production --compute-units 8

surreal cloud instance update production --version 3.2.4

surreal cloud instance update production --type production-4

Each change prints Set the <field> to <value>. on stderr as it is accepted. The command stops at the first request the API refuses, so earlier changes stay applied. On the platform a change of instance type counts as a storage change, so passing --type and --storage together can be refused at the storage step after the type has already changed. The Storage limits on Start page lists the storage each type starts with.

With the wait, the command then waits for the instance to be ready again and emits a fresh detail view. With --no-wait it hints at surreal cloud instance watch <name> and emits the instance as it stands.

Refusals, all exit 2:

• •

  No flags at all:

Nothing to update. Pass at least one of --type, --compute-units, --storage, --version, or --access-type.

• •

  --compute-units below 1 (Compute units start at 1.), or --storage below 1 (Storage starts at 1 GB.).

• •

  --storage while the storage cool-off is in force, naming the interval and, when known, when storage was last changed:

`production` cannot be resized yet: storage may be changed only once every 6 hours.
It was last changed at 2026-08-11T10:00:00Z.

• •

  --compute-units outside the current type's range, when --type is not also being changed:

`shared-1` accepts 1-2 compute units; 8 is outside that.

surreal cloud instance delete

Delete an instance and everything in it.

surreal cloud instance delete [OPTIONS] [INSTANCE]

surreal cloud instance delete staging

surreal cloud instance delete staging --force --json

The confirmation names the instance, its slug and its region, so the wrong terminal tab is caught before the request. Declining prints Nothing was deleted. and exits 0 with no document. In a non-interactive session without --force or --yes, it exits 2 having sent nothing.

The delete route answers with no body, so the emitted document is synthesised. Its state is deleted once the wait has seen the instance disappear, and deleting under --no-wait, which also hints at surreal cloud instance watch <name> --until deleted:

{
  "id": "67upif0m8sh1cn1p2c8t",
  "name": "staging",
  "slug": "staging-4jd1",
  "state": "deleted"
}

While waiting, a 404 is the success condition - there is nothing left to fetch.

surreal cloud instance pause

Pause a running instance.

surreal cloud instance pause [OPTIONS] [INSTANCE]

surreal cloud instance pause staging

With the wait, the command emits a fresh detail view once the instance has paused. With --no-wait it emits the accepted response and hints at surreal cloud instance watch <name> --until paused.

Pausing something already paused prints a note and still emits a document, exit 0. The shape of the answer does not change with remote state, so a script does not need to know which case it hit.

surreal cloud instance resume

Resume a paused instance.

surreal cloud instance resume [OPTIONS] [INSTANCE]

surreal cloud instance resume staging

Resuming something already ready behaves like pausing something already paused: a note, a document, exit 0. Resuming is usually slower than pausing, so the wait matters more here. With --no-wait the command hints at surreal cloud instance watch <name>.

surreal cloud instance watch

Watch an operation that was started elsewhere.

surreal cloud instance watch [OPTIONS] [INSTANCE]

There is no --wait or --no-wait here, because a watch is nothing but a wait. The exit codes are those of any wait: 10 on timeout, 6 when the instance settles in a different state, and 5 when it disappears while you wait for another state.

surreal cloud instance watch api

surreal cloud instance watch staging --until paused

surreal cloud instance watch api --json | jq -r '.event + " " + (.state // "")'

surreal cloud instance status

Show an instance's deployment phase and restorable snapshots.

surreal cloud instance status [OPTIONS] [INSTANCE]

Also accepts the list presentation flags, which arrange the snapshot table. Column ids are snapshot_id, started_at, tiers and on_demand, with valid_versions under --wide.

surreal cloud instance status production

The answer is one composite document: a phase, then the snapshots the instance can be restored from. In plain mode the phase is written as phase<tab><Phase> before the table, so grep ^phase works the same way it does on instance get. An instance with no restorable snapshots gets a note on stderr rather than an empty table with no explanation.

Snapshot ids from here are what instance create --restore-from expects.

surreal cloud instance endpoint

Print the endpoint a client connects to.

surreal cloud instance endpoint [OPTIONS] [INSTANCE]

This command has no options of its own.

The output is the bare endpoint plus a newline, byte-identical in rich and plain output, so $(…) captures exactly the value with no label and no styling.

ENDPOINT=$(surreal cloud instance endpoint production)
surreal db sql --endpoint "$ENDPOINT" --namespace app --database main

surreal cloud instance endpoint production --json

{
  "endpoint": "wss://production-6xk2.aws-euw1.surreal.cloud",
  "host": "production-6xk2.aws-euw1.surreal.cloud",
  "private_host": null,
  "access_type": "public"
}

The endpoint has the wss:// scheme. A private-only instance produces a warning on stderr rather than a refusal - the endpoint is still correct, it is simply not reachable from where you are. The endpoint carries no credential: to connect, add a token from instance token.

surreal cloud instance token

Mint a database token for an instance.

surreal cloud instance token [OPTIONS] [INSTANCE]

This is a database token - the credential a SurrealDB client authenticates with. It is not a personal access token, which authenticates against the control plane.

surreal cloud instance token production | pbcopy

SURREAL_TOKEN=$(surreal cloud instance token production) \
    surreal db sql --endpoint "$(surreal cloud instance endpoint production)" --namespace app --database main

To open a session without handling the token yourself, use instance sql, which does the same thing.

Refusals. Printing a credential into a terminal's scrollback is refused, exit 2, and the check happens before the token is minted - so a forgotten --reveal never costs a credential nobody can recover:

Refusing to print a database token to a terminal, where it would stay in your scrollback.
Pipe it:  surreal cloud instance token production | pbcopy
Or pass --reveal if you meant to see it.

Under --json the answer is a document with three fields, kind (instance_token), instance_id and token, so surreal cloud instance token production --json | jq -r .token works. Without --json, the bare token is the whole of stdout.

surreal cloud instance jwks

Fetch the key set that verifies an instance's tokens.

surreal cloud instance jwks [OPTIONS] [INSTANCE]

Also accepts the list presentation flags. Column ids are the JWK member names - kid, kty, alg and use, with crv under --wide - so a member the key type does not carry renders as missing rather than empty.

surreal cloud instance jwks production

surreal cloud instance jwks production --json > jwks.json

Under --json the whole key set is emitted, keys wrapper included, so it can be handed straight to a JWT library.

A key set is public, so this is the one instance route that does not need a Cloud session. Addressing the instance by id avoids any lookup; a name or slug still needs to list the organisation's instances first, which needs a credential.

Handing off to the database

sql, import and export do not speak SurrealQL themselves. Each one resolves the instance, mints a short-lived database token, and then becomes the matching database command, run through the surreal launcher:

What the handoff passes to the database:

• •

  --endpoint is added as <scheme>://<instance host>, unless the arguments after -- already contain --endpoint or -e, in which case yours is used and nothing is added.

• •

  The token is passed in the environment as SURREAL_TOKEN, never on the command line, so it does not appear in ps output or shell history.

• •

  --namespace and --database become SURREAL_NAMESPACE and SURREAL_DATABASE in the child's environment.

• •

  Everything after -- is forwarded unchanged, because the database's own flags are documented on its own pages and change independently. Pass them as you would to surreal db sql, surreal db import or surreal db export.

The database is reached only through the launcher, at the path the launcher records in SURREAL_CLI_LAUNCHER. The component does not search PATH for a surreal binary, install anything, or fetch the database itself. If the database is not installed, the launcher offers to install it when it runs the command. Unattended, in CI or with --no-input, the launcher exits 12 and names the install command instead. See surreal.

Run surreal-cloud directly rather than as surreal cloud and these three commands refuse with exit 2, because there is no launcher to hand off to. They check this first, before anything else, so no token is minted for nothing.

On Unix the handoff replaces the process, so the database command owns the terminal, signals and exit code. On Windows the command stays alive and forwards the database's exit code.

Two warnings, neither of which stops the handoff: the instance is private-only, so its host resolves only inside its own network, and the instance is paused, failed or deleted, so the connection will probably be refused. Connecting to <name> at <host>. goes to stderr as the last thing printed, so export -- - can be piped without the note getting into the data.

surreal cloud instance sql

Open a SurrealQL session against an instance.

surreal cloud instance sql [OPTIONS] [INSTANCE] [-- <ARGS>...]

This runs surreal db sql against the instance, as described in Handing off to the database.

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

surreal cloud instance sql production -- --ns app --db main --pretty

echo "SELECT count() FROM person GROUP ALL;" \
    | surreal cloud instance sql production --namespace app --database main

--namespace and --database are optional here, because surreal db sql accepts a session without them.

surreal cloud instance import

Import a file into an instance.

surreal cloud instance import [OPTIONS] [INSTANCE] [-- <ARGS>...]

This runs surreal db import against the instance, as described in Handing off to the database. The file is the positional argument of the database command, so it goes after the --.

surreal cloud instance import production --namespace app --database main -- ./seed.surql

Refusals. surreal db import requires both a namespace and a database, so this command does too. The check fires before a token is minted, exit 2:

`surreal cloud instance import` needs both --namespace and --database; `surreal import` requires them.

See surreal db import for the flags available after the --.

surreal cloud instance export

Export an instance to a file.

surreal cloud instance export [OPTIONS] [INSTANCE] [-- <ARGS>...]

This runs surreal db export against the instance, as described in Handing off to the database.

surreal cloud instance export production --namespace app --database main -- ./backup.surql

surreal cloud instance export production --namespace app --database main -- - | gzip > backup.surql.gz

Like import, this refuses a missing namespace or database before minting anything. The destination and the export selection flags, such as --tables or --only, belong to surreal db export. With no destination the database writes to stdout. Everything this command itself prints goes to stderr, so the dump on stdout stays clean.

For a managed snapshot rather than a SurrealQL dump, use instance backup create.

surreal cloud instance metrics

Show an instance's resource metrics.

surreal cloud instance metrics [OPTIONS] --metric <METRIC> [INSTANCE]

Also accepts the list presentation flags. Summary rows carry series, last, min, mean, max and unit, with samples and gaps under --wide; sample rows carry timestamp, series and value, with unit under --wide.

--metric is a free-form string rather than a fixed set, because the platform's metric vocabulary is not published anywhere the CLI can read it.

surreal cloud instance metrics production --metric cpu

surreal cloud instance metrics production \
    --metric memory \
    --from 2026-08-11T10:00:00Z \
    --to 2026-08-11T12:00:00Z \
    --samples

Timestamps are validated locally and forwarded byte-for-byte, never reformatted:

Ensure `11-08-2026` is an RFC3339 timestamp, such as 2026-08-11T10:00:00Z

--samples chooses a table, not a payload: --json carries the whole document either way. A note on stderr states the metric, its unit and the window, which matters when neither bound is given because the API then chooses the window. An empty window prints a note suggesting a wider --from or a check of the metric name.

surreal cloud instance logs

Show an instance's logs.

surreal cloud instance logs [OPTIONS] [INSTANCE]

Also accepts the list presentation flags. Column ids are timestamp, level and message, with pod under --wide.

surreal cloud instance logs production

surreal cloud instance logs production --level error,warn

surreal cloud instance logs production --follow --json | jq -r '.timestamp + " " + .message'

--level is a display filter applied on this side, and a note reports how many lines were hidden by it. --json still carries every line the API sent. --limit takes from the start of the window, matching its meaning elsewhere, so to read the most recent lines, narrow the window with --from.

--follow polls with a moving start time at a fixed five-second interval - there is no streaming endpoint and no interval flag. It runs until interrupted, and lines on the boundary between two polls are not printed twice. Under --follow --json, each new line is written as newline-delimited JSON on stdout; in text mode a table is printed per batch, with the header only on the first.

surreal cloud instance usage

Show what an instance has consumed.

surreal cloud instance usage [OPTIONS] [INSTANCE]

Accepts the list presentation flags and nothing else - this route takes no query parameters at all. Column ids are instance_id, metric_type, compute_hours, disk_used_bytes, period_start and period_end, with instance_type and source under --wide.

surreal cloud instance usage production

For every instance in the organisation at once, use org usage.

surreal cloud instance estimate

Estimate what an instance would cost.

surreal cloud instance estimate [OPTIONS] --type <SLUG> --region <REGION>

This command takes no positional argument: it prices a hypothetical instance, so there is nothing to name.

surreal cloud instance estimate --type production-4 --region aws-euw1 --units 8 --storage 250

Flags you omit are left out of the request rather than sent as null, so the platform's own defaults for that type apply. The estimate is for the organisation resolved from --org and the precedence chain. Nothing is created or billed. The result shows the type, the region, any units or storage you gave, the cost with its currency symbol, and the currency.

Refusals, exit 2:

An instance has at least 1 compute unit; 0 was given.
An instance has at least 1GB of storage; 0 was given.

This is the one place the API does not use integer minor units - the cost is a number in a named currency - and --json keeps the raw value.

surreal cloud instance capabilities get

Show an instance's capability configuration.

surreal cloud instance capabilities get [OPTIONS] [INSTANCE]

This command has no options of its own.

surreal cloud instance capabilities get production

The view lists allow_scripting, allow_guests and allow_insecure_storable_closures, then the allowed and denied list for each of experimental, arbitrary_query, eval_query, rpc_methods, http_endpoints, networks and functions, named as the API names them (allowed_functions, denied_networks and so on). A setting the API did not send is left out, which is different from an empty list: an explicitly empty list is shown as (none) and permits nothing in that category, while an absent one leaves SurrealDB's default in force. Capabilities this build does not know about are shown as they arrive.

Under --json the nested capabilities object is emitted, not the whole instance - so it can be diffed against another instance directly.

diff <(surreal cloud instance capabilities get staging --json) \
     <(surreal cloud instance capabilities get production --json)

surreal cloud instance capabilities set

Change an instance's capability configuration.

surreal cloud instance capabilities set [OPTIONS] [INSTANCE]

The capabilities route is a full replacement, so this command reads the current configuration, applies the flags given here, shows what would change, and asks before writing. A list flag replaces that list rather than adding to it, and anything not named is left exactly as it is - including capabilities this build does not know about.

surreal cloud instance capabilities set production --deny-scripting

surreal cloud instance capabilities set production --allow-funcs "array,string,time"

surreal cloud instance capabilities set production --deny-funcs "http::*" --force

The diff is printed on stderr in every output mode, --json included, then confirmed unless --force or the global --yes is given. --quiet suppresses the diff, so combine it with --force rather than with a prompt. Declining prints Nothing was changed. and exits 0. In a non-interactive session without --force or --yes, the command exits 2 having written nothing.

Flags for the same capability in opposite directions, such as --allow-scripting with --deny-scripting, are a usage error. A list flag may be given together with its opposite, for example --allow-funcs and --deny-funcs, and each replaces its own list. Setting a list to the value it already has is not a change. There is no flag for allow_insecure_storable_closures: set leaves it as it is.

On success the command prints the configuration now in force.

Refusals and short-circuits. No flags at all is a usage error, exit 2, before any request:

Nothing to set. Pass at least one capability flag, such as --allow-scripting or --deny-funcs http::*.
Run `surreal cloud instance capabilities get` to see the current configuration.

Flags that would change nothing produce a note and exit 0 without a write:

`production` already has those capabilities. Nothing was changed.

surreal cloud instance backup list

List the snapshots an instance can be restored from.

surreal cloud instance backup list [OPTIONS] [INSTANCE]

Accepts the list presentation flags and nothing else. Column ids are snapshot_id, started_at, tiers and on_demand, with valid_versions under --wide.

surreal cloud instance backup list production

surreal cloud instance backup list production --sort started_at --reverse --limit 1 \
    --columns snapshot_id --no-header

There is no backup collection route on the API, so this reads the snapshots off the instance's status route. --json carries the snapshot array rather than the whole status document, and an instance too new to have been backed up gives an empty array and a note. instance status shows the same snapshots alongside the deployment phase.

surreal cloud instance backup create

Take a backup of an instance now.

surreal cloud instance backup create [OPTIONS] [INSTANCE]

This command has no options of its own, and carries no --wait or --no-wait.

surreal cloud instance backup create production

The route answers with no body, so the document is synthesised:

{
  "instance_id": "67upif0m8sh1cn1p2c8t",
  "status": "accepted"
}

A replayed request is a second snapshot, so this call is not retried after a timeout or a 502. Requesting a backup while one is already queued answers with a 429 that is reported as a conflict, exit 6, rather than as a rate limit - the condition is "one is already running", not "you are asking too often". Only one on-demand backup runs at a time.

Poll instance backup list to see the snapshot appear.

surreal cloud instance backup policy get

Show the backup retention policy.

surreal cloud instance backup policy get [OPTIONS] [INSTANCE]

This command has no options of its own.

surreal cloud instance backup policy get production

The answer reports each retention tier, how often snapshots are taken, and which tiers this organisation's plan allows you to change - which is what backup policy set will accept.

surreal cloud instance backup policy set

Change the backup retention policy.

surreal cloud instance backup policy set [OPTIONS] [INSTANCE]

The three retention flags also accept the literal default, which restores this organisation's own value for that tier. --frequency-hours has no default form, because the platform gives it no resettable value.

--frequency-hours is an allow-list, not a range: the plan publishes the intervals it offers, and a value sitting between two of them is refused rather than rounded. Run backup policy get to see which intervals this plan offers.

surreal cloud instance backup policy set production --daily 14

surreal cloud instance backup policy set production --frequency-hours 6

surreal cloud instance backup policy set production --monthly default

Confirmation. Only a reduction asks. Lengthening a retention cannot lose a snapshot, so it is applied without a prompt. A reset to default counts as a reduction, because the organisation's own value is not known in advance. Changing only --frequency-hours never asks, because taking snapshots less often deletes none. The shortened tiers are listed on stderr and the question names the instance. Declining prints The policy was not changed. and exits 0. In a non-interactive session without --force or --yes, a reduction exits 2 having changed nothing.

Refusals, exit 2:

• •

  No flags at all:

Nothing to set. Pass --daily, --weekly, --monthly or --frequency-hours.
Each retention flag also takes the literal `default`, which restores this organization's own value for that tier.

• •

  A tier the plan does not allow changing:

This organization's plan does not allow changing the monthly retention on `production`.
Run `surreal cloud instance backup policy get` to see which tiers are editable.

• •

  A value outside the plan's bounds, naming the bound it broke:

Daily retention must be between 1 and 30 days on this plan; 90 was given.

• •

  A --frequency-hours the plan does not offer, listing the intervals it does:

A backup every 5 hours is not offered on this plan. Choose one of: 6, 12, 24.

Related pages

• •

  Long-running operations - --wait, --no-wait, polling and exit code 10

• •

  org commands - the organisation that owns these instances

• •

  catalog commands - the type, region and version slugs create and update expect

• •

  The surreal launcher - how sql, import and export reach the database component

• •

  Overview - the rest of the reference

• •

  SurrealDB CLI - the data plane: surreal db sql, surreal db import, surreal db export