> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt # Instances with surreal cloud Deploy, find, connect to, scale, pause, back up, set capabilities on, and delete SurrealDB Cloud instances with the surreal cloud instance commands. This page walks through everyday instance work from the command line: creating an 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](/docs/explore/cli/cloud/authentication.md) if not. For every flag on every verb, see the [`surreal cloud` reference](/docs/reference/cli/cloud/commands/instance.md). ## 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. ```bash surreal cloud org use acme ``` `--org` overrides it for a single command, and `SURREAL_CLOUD_ORG` overrides it for a shell. See [Organisations](/docs/explore/cli/cloud/organisations.md#choosing-an-organisation) for the full order of precedence. Two catalogues tell you what you can deploy. ```bash surreal cloud catalog regions surreal cloud catalog instance-types surreal cloud catalog instance-versions surreal cloud catalog storage-types surreal cloud org plans ``` `catalog` lists what the platform offers in general. `org plans` is narrower and organisation-specific - it is the one to trust before a `create`. ## Create an instance surreal cloud instance create [OPTIONS] --type --region Price it first if the cost matters, then deploy. ```bash surreal cloud instance estimate --type shared-1 --region aws-euw1 surreal cloud instance create production --type shared-1 --region aws-euw1 ``` ", "required": true, "description": "A name for the instance. 1 to 30 characters." }, { "name": "--type", "value": "", "required": true, "description": "The instance type, by slug. See `surreal cloud catalog instance-types`." }, { "name": "--region", "value": "", "required": true, "description": "The region to deploy into, by slug. See `surreal cloud catalog regions`." }, { "name": "--version", "value": "", "description": "The SurrealDB version to run. Defaults to the platform's current one." }, { "name": "--compute-units", "value": "", "description": "How many compute units to run, for the types that scale." }, { "name": "--storage", "value": "", "description": "Storage to allocate, in gigabytes." }, { "name": "--access-type", "value": "", "description": "How the instance may be reached: `public`, `private`, or `dual`." }, { "name": "--restore-from", "value": "", "description": "Restore from a snapshot, as `/`." } ]} /> `create` 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. > [!WARNING] > Creating an instance is not idempotent. A retried `instance create` is a second instance and a second bill. `surreal cloud` never replays a create automatically for this reason - if a create fails without a clear answer, run `surreal cloud instance list` before trying again. ## 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. ```bash 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 ```bash 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 ```bash 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](/docs/explore/cli/components.md). 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. ```bash 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. ```bash 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 ```bash 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. > [!IMPORTANT] > Every change in this list restarts the instance. Plan updates the way you would plan a deployment, and expect a reconnect window. Storage can only be changed once every few hours; `surreal cloud` reports the cool-off and when the last change happened rather than sending a request that would be refused. A type change starts the cool-off as well, so change `--type` and `--storage` in separate invocations. ## Pause and resume ```bash 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. ```bash 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 `create`, `update`, `delete`, `pause`, and `resume` wait for the instance to settle before they return. ", "default": "15m", "description": "How long to wait before giving up, such as `90s` or `20m`." } ]} /> 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 ` picks the state back up. ## Read state, logs, and metrics ```bash 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. For the equivalent views in the browser, see [Monitoring](/docs/manage/instances/monitoring.md). ## Backups ```bash 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. ```bash 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](/docs/manage/instances/backups.md) for retention behaviour and what a snapshot contains. ## Capabilities Capabilities decide what SurrealQL running on the instance may do: scripting, guest access, outbound network access, which functions and RPC methods are permitted. ```bash 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](/docs/manage/instances/configure.md) and [Network access](/docs/manage/instances/network-access.md). ## Delete an instance ```bash 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 ```bash title="review-env.sh" #!/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 ```bash title="pause-overnight.sh" #!/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 ```bash title="clone-production.sh" #!/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](/docs/explore/cli/cloud/organisations.md) - members, roles, invitations, usage, and spend. - [Scripting](/docs/explore/cli/cloud/scripting.md) - exit codes and the `--json` contract in full. - [`surreal cloud` reference](/docs/reference/cli/cloud/commands/instance.md) - every instance flag and default.