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

# surreal cloud config

Reference for surreal cloud config - listing, reading, setting and clearing configuration values, printing the file path, and opening it in an editor.

`surreal cloud config` reads and writes the CLI's own configuration file. Nothing here sends a request: the file never leaves the machine.

<Synopsis>
surreal cloud config <COMMAND> [OPTIONS]
</Synopsis>

| Verb | Purpose | Alias |
| --- | --- | --- |
| [`list`](#config-list) | List every configuration key and its value | `ls` |
| [`get`](#config-get) | Show one configuration value | |
| [`set`](#config-set) | Set a configuration value | |
| [`unset`](#config-unset) | Clear a configuration value | |
| [`path`](#config-path) | Print the path to the configuration file | |
| [`edit`](#config-edit) | Open the configuration file in your editor | |

Every verb works on **one profile** - whichever `--profile`, `SURREAL_CLOUD_PROFILE` and the file's own `active_profile` settle on - and each one says which profile it touched.

## The keys

Four keys are recognised. Each is outranked by an environment variable, and by a command-line flag above that; see the [precedence chain](/docs/reference/cli/cloud/global-flags.md#the-precedence-chain).

| Key | Type | Description | Outranked by |
| --- | --- | --- | --- |
| `org` | Text | Default organisation for this profile | `SURREAL_CLOUD_ORG` |
| `api` | URL | Base URL of the SurrealDB API | `SURREAL_CLOUD_API` |
| `json` | Boolean | Always emit machine-readable JSON | `SURREAL_CLOUD_JSON` |
| `plain` | Boolean | Always disable tables, spinners and relative times | `SURREAL_CLOUD_PLAIN` |

The persisted context - what [`org use`](/docs/reference/cli/cloud/commands/org.md#org-use) records - is **not** reachable from here. There is no `config set context.org`. The two live in separate tables of the same file so that `org use` never overwrites an `org` value you set by hand, and the hand-written one wins.

```toml title="config.toml"
active_profile = "work"

[profile.work]
org = "acme"          # written by a person

[profile.work.context]
org = "67upif0m8sh1cn1p2c8t"   # written by `org use`
```

Keys this build has never heard of are preserved on write, so an older binary editing a newer file does not discard anything.

## surreal cloud config list {#config-list}

List every configuration key and its value.

<Synopsis>
surreal cloud config list [OPTIONS]
</Synopsis>

This command takes no positional arguments and no options of its own.

Accepts the [list presentation flags](/docs/reference/cli/cloud/output-and-exit-codes.md#list-presentation-flags). Column ids are `key`, `value`, `set` and `description`, with `kind` under `--wide`.

```bash
surreal cloud config list
```

```text title="Output"
KEY              VALUE   SET  DESCRIPTION
org              acme    yes  Default organization for this profile
api                      no   Base URL of the SurrealDB API
json                     no   Always emit machine-readable JSON
plain                    no   Always disable tables, spinners and relative times
```

Every key is listed whether or not it is set, and the `set` column is what distinguishes a configured value from a default. Only a key this profile has actually set carries a value, so an unset key - `api` above, which falls back to the built-in default - has an empty `value` cell. A note on stderr reports the profile and the file path.

## surreal cloud config get {#config-get}

Show one configuration value.

<Synopsis>
surreal cloud config get [OPTIONS] <KEY>
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "<KEY>",
            "required": true,
            "description": "The configuration key."
        }
    ]}
/>

This command has no options of its own.

The output is the value alone plus a newline, with no label and no styling, so `$(…)` captures exactly the value. An unset key writes **zero bytes**, so `[ -z "$(surreal cloud config get org)" ]` and `wc -l` agree with each other.

```bash
ORG=$(surreal cloud config get org)
```

```bash title="Branch on whether a key is set"
if [ -z "$(surreal cloud config get org)" ]; then
    echo "no default organisation for this profile"
fi
```

**Refusals.** An unrecognised key is a usage error, exit `2`, and lists the keys that exist.

## surreal cloud config set {#config-set}

Set a configuration value.

<Synopsis>
surreal cloud config set [OPTIONS] <KEY> <VALUE>
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "<KEY>",
            "required": true,
            "description": "The configuration key."
        },
        {
            "name": "<VALUE>",
            "required": true,
            "description": "The value to store."
        }
    ]}
/>

This command has no options of its own.

```bash title="Always emit JSON from this profile"
surreal cloud config set json true
```

```bash title="Point at a different API"
surreal cloud config set api https://api.example.com
```

```bash title="Configure a second profile"
surreal cloud --profile staging config set org contoso
```

**Warnings.** When the corresponding environment variable is exported, the command says so, because the variable silently outranks what you just wrote:

```text
warning: SURREAL_CLOUD_JSON is set and takes precedence over this. Unset it for the configured value to apply.
```

**Refusals**, exit `2`: an unrecognised key, or a value the key's type rejects - a non-boolean for `json`, or a URL with a path for `api`.

## surreal cloud config unset {#config-unset}

Clear a configuration value.

<Synopsis>
surreal cloud config unset [OPTIONS] <KEY>
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "<KEY>",
            "required": true,
            "description": "The configuration key."
        }
    ]}
/>

This command has no options of its own.

```bash
surreal cloud config unset json
```

Clearing a key restores the CLI's default rather than falling back to another profile. Clearing an already-unset key is a no-op that succeeds.

## surreal cloud config path {#config-path}

Print the path to the configuration file.

<Synopsis>
surreal cloud config path [OPTIONS]
</Synopsis>

This command takes no positional arguments and no options of its own.

The output is the path alone plus a newline.

```bash
surreal cloud config path
```

```text title="Output"
/Users/ana/.surrealdb/cloud/config.toml
```

```bash title="Back the file up before editing it"
cp "$(surreal cloud config path)" "$(surreal cloud config path).bak"
```

`credentials.json` lives beside it in the same directory. See [credential storage](/docs/reference/cli/cloud/authentication.md#where-credentials-are-stored) for how that directory is chosen.

## surreal cloud config edit {#config-edit}

Open the configuration file in your editor.

<Synopsis>
surreal cloud config edit [OPTIONS]
</Synopsis>

This command takes no positional arguments and no options of its own.

```bash
surreal cloud config edit
```

The file is opened with `$VISUAL`, or `$EDITOR` when that is unset. A value such as `code --wait` works, because it is split on whitespace. The file is created first if it does not exist yet, and re-read when the editor exits, so a mistake is reported while the editor is still fresh in mind: `<path> is valid, with N profiles.` on success, and the parse error on failure. A broken file is left in place for you to fix.

With no terminal there is nothing to attach an editor to, so in a non-interactive session the command exits `2` rather than hanging; use [`config set`](#config-set) instead. It also exits `2` when neither variable is set.

Editing the file by hand is supported - [`config list`](#config-list) will show whatever you wrote, and unknown keys survive - but a file written by a newer `surreal cloud` is refused rather than migrated:

```text
<path> was written by a newer surreal-cloud (file version 2, this build understands 1).
Refusing to touch it - upgrade surreal-cloud, or point --config elsewhere.
```

## Related pages

- [Global flags](/docs/reference/cli/cloud/global-flags.md) - the flags and environment variables these keys sit beneath
- [`context` commands](/docs/reference/cli/cloud/commands/context.md) - switching between profiles
- [`org use`](/docs/reference/cli/cloud/commands/org.md#org-use) - remembering an organisation within a profile
- [Authentication](/docs/reference/cli/cloud/authentication.md#where-credentials-are-stored) - the credential file beside this one
- [surreal cloud reference](/docs/reference/cli/cloud.md) - the rest of the reference