surreal cloud config

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

surreal cloud config <COMMAND> [OPTIONS]

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.

The persisted context - what 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.

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

List every configuration key and its value.

surreal cloud config list [OPTIONS]

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

Accepts the list presentation flags. Column ids are key, value, set and description, with kind under --wide.

surreal cloud config list

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

Show one configuration value.

surreal cloud config get [OPTIONS] <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.

ORG=$(surreal cloud config get org)

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

Set a configuration value.

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

This command has no options of its own.

surreal cloud config set json true

surreal cloud config set api https://api.example.com

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:

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

Clear a configuration value.

surreal cloud config unset [OPTIONS] <KEY>

This command has no options of its own.

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

Print the path to the configuration file.

surreal cloud config path [OPTIONS]

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

The output is the path alone plus a newline.

surreal cloud config path

/Users/ana/.surrealdb/cloud/config.toml

cp "$(surreal cloud config path)" "$(surreal cloud config path).bak"

credentials.json lives beside it in the same directory. See credential storage for how that directory is chosen.

surreal cloud config edit

Open the configuration file in your editor.

surreal cloud config edit [OPTIONS]

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

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 instead. It also exits 2 when neither variable is set.

Editing the file by hand is supported - 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:

<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 - the flags and environment variables these keys sit beneath

• •

  context commands - switching between profiles

• •

  org use - remembering an organisation within a profile

• •

  Authentication - the credential file beside this one

• •

  surreal cloud reference - the rest of the reference