# Global flags

The sixteen flags every surrealctl command accepts, the environment variable behind each one, the precedence chain that resolves them, and the duration syntax.

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:

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

<OptionsTable
    title="Context flags"
    options={[
        {
            "name": "--profile",
            "value": "<PROFILE>",
            "default": "default",
            "env": "SURREALCTL_PROFILE",
            "description": "The configuration profile to use. A profile bundles a credential, an API base URL and a set of configuration values."
        },
        {
            "name": "--config",
            "value": "<PATH>",
            "env": "SURREALCTL_CONFIG",
            "description": "Path to the configuration file. Its directory also becomes the credential directory."
        },
        {
            "name": "--org",
            "value": "<ORG>",
            "env": "SURREALCTL_ORG",
            "description": "The organisation to operate on, by id or name."
        }
    ]}
/>

## Authentication

<OptionsTable
    title="Authentication flags"
    options={[
        {
            "name": "--token",
            "value": "<TOKEN>",
            "env": "SURREALCTL_TOKEN",
            "description": "Personal access token to authenticate with. Conflicts with `--token-file`, and is never persisted."
        },
        {
            "name": "--token-file",
            "value": "<PATH>",
            "env": "SURREALCTL_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": "SURREALCTL_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/surrealctl/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": "SURREALCTL_JSON",
            "description": "Emit machine-readable JSON on stdout. See the output contract for what is guaranteed."
        },
        {
            "name": "--plain",
            "env": "SURREALCTL_PLAIN",
            "description": "Disable tables, spinners and relative times. Output becomes tab-separated and 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": "SURREALCTL_YES",
            "description": "Assume yes for every confirmation in this invocation."
        },
        {
            "name": "--no-input",
            "env": "SURREALCTL_NO_INPUT",
            "description": "Never prompt for input; fail instead. Also spelled `--non-interactive`."
        }
    ]}
/>

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

<OptionsTable
    title="Logging flags"
    options={[
        {
            "name": "--log",
            "value": "<FILTER>",
            "default": "warn",
            "env": "SURREALCTL_LOG",
            "description": "The logging level, or a full set of filter directives."
        },
        {
            "name": "--debug",
            "env": "SURREALCTL_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": "SURREALCTL_TIMEOUT",
            "description": "Maximum time to wait for a single API request."
        },
        {
            "name": "--retries",
            "value": "<N>",
            "default": "3",
            "env": "SURREALCTL_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/surrealctl/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 SURREALCTL_ORG, or run `surrealctl org use <name>`.

Available:
  acme
  contoso
```

`--debug` prints which layer won each value, and [`context show`](/docs/reference/cli/surrealctl/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`, `--wait-timeout` and `spectron access-token create --ttl` all 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
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](/docs/manage/surrealctl/install.md#the-surreal-handoff): `SURREAL_TOKEN`, `SURREAL_NAMESPACE` and `SURREAL_DATABASE`.

### Variables that mirror a flag

| Variable | Flag |
| --- | --- |
| `SURREALCTL_PROFILE` | `--profile` |
| `SURREALCTL_CONFIG` | `--config` |
| `SURREALCTL_ORG` | `--org` |
| `SURREALCTL_TOKEN` | `--token` |
| `SURREALCTL_TOKEN_FILE` | `--token-file` |
| `SURREALCTL_API` | `--api` |
| `SURREALCTL_JSON` | `--json` |
| `SURREALCTL_PLAIN` | `--plain` |
| `SURREALCTL_YES` | `--yes` |
| `SURREALCTL_NO_INPUT` | `--no-input` |
| `SURREALCTL_LOG` | `--log` |
| `SURREALCTL_DEBUG` | `--debug` |
| `SURREALCTL_TIMEOUT` | `--timeout` |
| `SURREALCTL_RETRIES` | `--retries` |

### Variables with no flag

| Variable | Effect |
| --- | --- |
| `SURREALCTL_CONFIG_DIR` | Overrides the configuration and credential directory |
| `SURREALCTL_SURREAL_BINARY` | Path to the `surreal` binary used by `instance sql`, `import` and `export` |
| `SURREALCTL_AGENT` | `1` or `0`, forcing agent detection on or off |
| `SURREALCTL_CLOUD_TOKEN` | Supplies an already-minted Cloud session token, for support reproduction |
| `SURREALCTL_AUTH_CLIENT_ID` | Overrides the OAuth client id, for a non-production tenant |
| `SURREALCTL_AUTH_ISSUER` | Overrides the OAuth issuer, for a non-production tenant |

### 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 |
| `XDG_CONFIG_HOME`, `HOME` | Locate the configuration directory |
| `HTTPS_PROXY`, `NO_PROXY` | Proxy the API connection |
| `EDITOR` | Used by [`config edit`](/docs/reference/cli/surrealctl/commands/config.md#config-edit) |

## Configuration file equivalents

Five values can be persisted per profile with [`config set`](/docs/reference/cli/surrealctl/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` | `SURREALCTL_ORG` |
| `api` | `SURREALCTL_API` |
| `json` | `SURREALCTL_JSON` |
| `plain` | `SURREALCTL_PLAIN` |
| `surreal_binary` | `SURREALCTL_SURREAL_BINARY` |

## Related pages

- [Output and exit codes](/docs/reference/cli/surrealctl/output-and-exit-codes.md) — what `--json`, `--plain` and `--quiet` actually produce
- [`config` commands](/docs/reference/cli/surrealctl/commands/config.md) — reading and writing the configuration file
- [`context` commands](/docs/reference/cli/surrealctl/commands/context.md) — switching profiles
- [Overview](/docs/reference/cli/surrealctl/overview.md) — the rest of the reference
- [SurrealDB CLI](/docs/reference/cli/surrealdb-cli/overview.md) — the data plane, and its own [environment variables](/docs/reference/cli/surrealdb-cli/environment-variables.md): the `SURREAL_*` set this CLI never reads