Global flags

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

surrealctl --json instance list
surrealctl instance --json list
surrealctl 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 SURREALCTL_* 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 SURREALCTL_ORG, or run `surrealctl 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, --wait-timeout and spectron access-token create --ttl all accept the same syntax. A bare number means seconds.

surrealctl --timeout 90 instance list
surrealctl instance create api --type shared-1 --region aws-euw1 --wait-timeout 5m
surrealctl spectron access-token create --ttl 2h

The SURREALCTL_ prefix

Every environment variable this CLI reads is prefixed SURREALCTL_, and never SURREAL_.

Reusing the sibling's prefix would be actively harmful rather than merely untidy. 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 surrealctl sets for the surreal child process during the handoff: SURREAL_TOKEN, SURREAL_NAMESPACE and SURREAL_DATABASE.

Variables that mirror a flag

Variables with no flag

Conventions it honours

Configuration file equivalents

Five 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

• •

  Overview — the rest of the reference

• •

  SurrealDB CLI — the data plane, and its own environment variables: the SURREAL_* set this CLI never reads