surreal cloud global flags

Sixteen flags are accepted by every surreal cloud command. They may appear anywhere after cloud - before the group, between the group and the verb, or after the verb - so all three of these are the same invocation:

surreal cloud --json instance list
surreal cloud instance --json list
surreal cloud instance list --json

--help groups them under four headings, and this page keeps those groups.

Context

Authentication

--token has no short form on purpose: -t reads as --type on the instance commands, and a credential belongs in the environment or a file rather than in argv. See Authentication.

A base URL with a path of its own is refused as a usage error, because the client appends its own routes and the path would be silently prepended to every one of them:

Ensure the API base has no path, such as https://api.surrealdb.com

Output

--color is the one flag with no SURREAL_CLOUD_* variable. Colour also honours the NO_COLOR, FORCE_COLOR and CLICOLOR_FORCE conventions.

--json and --plain are independent axes: --json chooses the encoding, --plain the decoration. Passing both is accepted and --plain is ignored, because CI scripts pass both and erroring on that is hostile.

Logging

--help files the request timeout and the retry budget under this heading alongside the log level.

The effective per-request timeout is never shorter than 21 seconds, because the API's own upstream timeout is 20 seconds and giving up sooner abandons requests that are still being worked on.

The precedence chain

Every value that can come from more than one place is resolved once, before the command runs, in this order - highest first:

1. 1.

   A command-line flag

2. 2.

   An environment variable

3. 3.

   The profile in config.toml

4. 4.

   The persisted context, written by org use

5. 5.

   Your account's default organisation, as the API reports it

6. 6.

   The only candidate, when exactly one exists

7. 7.

   An interactive picker, when a person is present

8. 8.

   An error naming the flag that would have settled it

Layers 5 to 7 apply to the organisation specifically. Exactly one candidate is not a choice, so it is used silently; several candidates in a non-interactive session is an error rather than a guess:

Several organizations are available and none was chosen.
Pass --org, set SURREAL_CLOUD_ORG, or run `surreal cloud org use <name>`.

Available:
  acme
  contoso

--debug prints which layer won each value, and context show reports it as part of its answer:

An organisation reference that already looks like an id is used with no lookup at all. A name or slug costs one request to resolve, and an unrecognised one is answered with did-you-mean candidates.

Duration syntax

--timeout and --wait-timeout accept the same syntax. A bare number means seconds.

surreal cloud --timeout 90 instance list
surreal cloud instance create api --type shared-1 --region aws-euw1 --wait-timeout 5m

The SURREAL_CLOUD_ prefix

Every environment variable this component reads is prefixed SURREAL_CLOUD_, and never plain SURREAL_.

Reusing the database's prefix would be harmful. SURREAL_TOKEN in a shell means a database JWT for one instance; reading it as a control-plane credential would send database tokens to api.surrealdb.com on every command.

The only SURREAL_* variables involved are ones surreal cloud sets for the database process during the handoff in instance sql, import and export: SURREAL_TOKEN, and SURREAL_NAMESPACE and SURREAL_DATABASE when given.

Variables that mirror a flag

Variables with no flag

Launcher variables

surreal cloud runs under the launcher, which sets SURREAL_CLI_LAUNCHER to its own path so that the handoff commands can reach the database through it. SURREAL_CLI_HOME (default ~/.surrealdb) moves the directory that holds both the launcher's files and the cloud configuration directory, and SURREAL_CLI_OFFLINE=1 forbids all network use by the launcher. The launcher reference documents these.

Conventions it honours

Deprecated SURREALCTL_ aliases

Before it became surreal cloud, the tool was surrealctl and every variable above carried the prefix SURREALCTL_ instead. The old names keep working, so a CI job that exports SURREALCTL_TOKEN does not break when it picks up the new release. The old name is consulted only when the new one is unset, and a run that uses any of them prints one warning on stderr listing each old name with its replacement:

SURREALCTL_* variables are deprecated. Rename SURREALCTL_TOKEN to SURREAL_CLOUD_TOKEN.

Two variables are not a plain prefix swap. SURREALCTL_CLOUD_TOKEN is now SURREAL_CLOUD_SESSION_TOKEN, because SURREAL_CLOUD_CLOUD_TOKEN would read as a typo. SURREALCTL_SURREAL_BINARY and the surreal_binary configuration key no longer exist, because the database is reached only through the launcher. Variables under the old prefix that never had a meaning are not mentioned.

Configuration file equivalents

Four values can be persisted per profile with config set. Each is outranked by its environment variable, and config set warns when that variable is exported.

Related pages

• •

  Output and exit codes - what --json, --plain and --quiet actually produce

• •

  config commands - reading and writing the configuration file

• •

  context commands - switching profiles

• •

  surreal cloud reference - the rest of the reference

• •

  Database environment variables - the SURREAL_* set this component never reads