> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# surreal cloud global flags

The sixteen flags every surreal cloud command accepts, the environment variable behind each one, the precedence chain that resolves them, the duration syntax, and the deprecated SURREALCTL_ aliases.

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:

```bash
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

<OptionsTable
    title="Context flags"
    options={[
        {
            "name": "--profile",
            "value": "<PROFILE>",
            "default": "default",
            "env": "SURREAL_CLOUD_PROFILE",
            "description": "The configuration profile to use. A profile bundles a credential, an API base URL and a set of configuration values. When the flag is absent, the file's `active_profile` applies, then `default`."
        },
        {
            "name": "--config",
            "value": "<PATH>",
            "env": "SURREAL_CLOUD_CONFIG",
            "description": "Path to the configuration file, or to the directory that holds it. The directory also becomes the credential directory."
        },
        {
            "name": "--org",
            "value": "<ORG>",
            "env": "SURREAL_CLOUD_ORG",
            "description": "The organisation to operate on, by id or name."
        }
    ]}
/>

## Authentication

<OptionsTable
    title="Authentication flags"
    options={[
        {
            "name": "--token",
            "value": "<TOKEN>",
            "env": "SURREAL_CLOUD_TOKEN",
            "description": "Personal access token to authenticate with. Conflicts with `--token-file`, and is never persisted."
        },
        {
            "name": "--token-file",
            "value": "<PATH>",
            "env": "SURREAL_CLOUD_TOKEN_FILE",
            "description": "Read the personal access token from a file, or `-` for standard input. Conflicts with `--token`."
        },
        {
            "name": "--api",
            "value": "<URL>",
            "default": "https://api.surrealdb.com",
            "env": "SURREAL_CLOUD_API",
            "description": "Base URL of the SurrealDB API. Must be absolute, `http` or `https`, name a host, and carry no path."
        }
    ]}
/>

`--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](/docs/reference/cli/cloud/authentication.md#personal-access-tokens).

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:

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

## Output

<OptionsTable
    title="Output flags"
    options={[
        {
            "name": "--json",
            "short": "-j",
            "env": "SURREAL_CLOUD_JSON",
            "description": "Emit machine-readable JSON on stdout. See the output contract for what is guaranteed."
        },
        {
            "name": "--plain",
            "env": "SURREAL_CLOUD_PLAIN",
            "description": "Disable tables, spinners and relative times. Output becomes width-independent."
        },
        {
            "name": "--color",
            "value": "<WHEN>",
            "default": "auto",
            "description": "When to use colour in output: `auto`, `always` or `never`."
        },
        {
            "name": "--quiet",
            "short": "-q",
            "description": "Suppress progress and informational output. The data payload on stdout is unaffected."
        },
        {
            "name": "--yes",
            "short": "-y",
            "env": "SURREAL_CLOUD_YES",
            "description": "Assume yes for every confirmation in this invocation."
        },
        {
            "name": "--no-input",
            "env": "SURREAL_CLOUD_NO_INPUT",
            "description": "Never prompt for input; fail instead. Also spelled `--non-interactive`."
        }
    ]}
/>

`--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.

<OptionsTable
    title="Logging flags"
    options={[
        {
            "name": "--log",
            "value": "<FILTER>",
            "default": "warn",
            "env": "SURREAL_CLOUD_LOG",
            "description": "The logging level, or a full set of filter directives."
        },
        {
            "name": "--debug",
            "env": "SURREAL_CLOUD_DEBUG",
            "description": "Log every API request and response to stderr, with the credential reduced to a digest. Also reports which precedence layer supplied each resolved value."
        },
        {
            "name": "--timeout",
            "value": "<DURATION>",
            "default": "30s",
            "env": "SURREAL_CLOUD_TIMEOUT",
            "description": "Maximum time to wait for a single API request."
        },
        {
            "name": "--retries",
            "value": "<N>",
            "default": "3",
            "env": "SURREAL_CLOUD_RETRIES",
            "description": "How many times to retry a failed request. The number of attempts is one more than this."
        }
    ]}
/>

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. A command-line flag
2. An environment variable
3. The profile in `config.toml`
4. The persisted context, written by [`org use`](/docs/reference/cli/cloud/commands/org.md#org-use)
5. Your account's default organisation, as the API reports it
6. The only candidate, when exactly one exists
7. An interactive picker, when a person is present
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:

```text
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`](/docs/reference/cli/cloud/commands/context.md#context-show) reports it as part of its answer:

| Layer | Reported as |
| --- | --- |
| Command-line flag | `command-line flag` |
| Environment variable | `environment variable` |
| Profile in `config.toml` | `profile in config.toml` |
| Persisted context | `persisted context (org use)` |
| Account default | `your account's default organization` |
| Single candidate | `the only candidate` |
| Interactive picker | `interactive choice` |

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.

> [!NOTE]
> A configured `api` value applies only when `--api` was not given. Because the flag has a default, the CLI cannot distinguish "absent" from "passed exactly the default", so passing `--api https://api.surrealdb.com` explicitly leaves the configured value unused.

## Duration syntax

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

| Suffix | Unit |
| --- | --- |
| *(none)*, `s`, `sec`, `secs`, `second`, `seconds` | Seconds |
| `ms` | Milliseconds |
| `m`, `min`, `mins`, `minute`, `minutes` | Minutes |
| `h`, `hr`, `hrs`, `hour`, `hours` | Hours |
| `d`, `day`, `days` | Days |

```bash
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`](/docs/reference/cli/cloud/commands/instance.md#instance-sql): `SURREAL_TOKEN`, and `SURREAL_NAMESPACE` and `SURREAL_DATABASE` when given.

### Variables that mirror a flag

| Variable | Flag |
| --- | --- |
| `SURREAL_CLOUD_PROFILE` | `--profile` |
| `SURREAL_CLOUD_CONFIG` | `--config` |
| `SURREAL_CLOUD_ORG` | `--org` |
| `SURREAL_CLOUD_TOKEN` | `--token` |
| `SURREAL_CLOUD_TOKEN_FILE` | `--token-file` |
| `SURREAL_CLOUD_API` | `--api` |
| `SURREAL_CLOUD_JSON` | `--json` |
| `SURREAL_CLOUD_PLAIN` | `--plain` |
| `SURREAL_CLOUD_YES` | `--yes` |
| `SURREAL_CLOUD_NO_INPUT` | `--no-input` |
| `SURREAL_CLOUD_LOG` | `--log` |
| `SURREAL_CLOUD_DEBUG` | `--debug` |
| `SURREAL_CLOUD_TIMEOUT` | `--timeout` |
| `SURREAL_CLOUD_RETRIES` | `--retries` |

### Variables with no flag

| Variable | Effect |
| --- | --- |
| `SURREAL_CLOUD_CONFIG_DIR` | Overrides the configuration and credential directory |
| `SURREAL_CLOUD_AGENT` | `1` or `0`, forcing agent detection on or off |
| `SURREAL_CLOUD_SESSION_TOKEN` | Supplies an already-minted Cloud session token, for support reproduction |
| `SURREAL_CLOUD_AUTH_CLIENT_ID` | Overrides the OAuth client id, for a non-production tenant |
| `SURREAL_CLOUD_AUTH_ISSUER` | Overrides the OAuth issuer, for a non-production tenant |

### 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](/docs/reference/cli/launcher.md) documents these.

### Conventions it honours

| Variable | Effect |
| --- | --- |
| `NO_COLOR` | Disables colour |
| `FORCE_COLOR`, `CLICOLOR_FORCE` | Enables colour, even when piped |
| `CI` | Selects plain, structural output. `CI=false`, `CI=0` and an empty value all mean *not* CI |
| `TERM=dumb` | Selects plain output with no colour |
| `SSH_CONNECTION`, `SSH_TTY` | Skips the browser login flow |
| `HOME`, `SURREAL_CLI_HOME` | Locate the configuration directory |
| `HTTPS_PROXY`, `NO_PROXY` | Proxy the API connection |
| `VISUAL`, `EDITOR` | Used by [`config edit`](/docs/reference/cli/cloud/commands/config.md#config-edit), in that order |

## 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:

```text
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`](/docs/reference/cli/cloud/commands/config.md#config-set). Each is outranked by its environment variable, and `config set` warns when that variable is exported.

| Key | Environment variable |
| --- | --- |
| `org` | `SURREAL_CLOUD_ORG` |
| `api` | `SURREAL_CLOUD_API` |
| `json` | `SURREAL_CLOUD_JSON` |
| `plain` | `SURREAL_CLOUD_PLAIN` |

## Related pages

- [Output and exit codes](/docs/reference/cli/cloud/output-and-exit-codes.md) - what `--json`, `--plain` and `--quiet` actually produce
- [`config` commands](/docs/reference/cli/cloud/commands/config.md) - reading and writing the configuration file
- [`context` commands](/docs/reference/cli/cloud/commands/context.md) - switching profiles
- [surreal cloud reference](/docs/reference/cli/cloud.md) - the rest of the reference
- [Database environment variables](/docs/reference/cli/db/environment-variables.md) - the `SURREAL_*` set this component never reads