config

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

surrealctl config <COMMAND> [OPTIONS]

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

The keys

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

surrealctl config list

List every configuration key and its value.

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

surrealctl 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
surreal_binary           no   Path to the `surreal` binary for sql/import/export

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.

surrealctl config get

Show one configuration value.

surrealctl 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 "$(surrealctl config get org)" ] and wc -l agree with each other.

ORG=$(surrealctl config get org)

if [ -z "$(surrealctl config get surreal_binary)" ]; then
    echo "using surreal from PATH"
fi

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

surrealctl config set

Set a configuration value.

surrealctl config set [OPTIONS] <KEY> <VALUE>

This command has no options of its own.

surrealctl config set json true

surrealctl config set surreal_binary /opt/surrealdb/3.2.4/surreal

surrealctl --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: SURREALCTL_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.

surrealctl config unset

Clear a configuration value.

surrealctl config unset [OPTIONS] <KEY>

This command has no options of its own.

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

surrealctl config path

Print the path to the configuration file.

surrealctl config path [OPTIONS]

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

The output is the path alone plus a newline.

surrealctl config path

/Users/ana/.config/surrealctl/config.toml

cp "$(surrealctl config path)" "$(surrealctl config path).bak"

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

surrealctl config edit

Open the configuration file in your editor.

surrealctl config edit [OPTIONS]

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

surrealctl config edit

The file is opened with $EDITOR. Editing it by hand is supported — config list will show whatever you wrote, and unknown keys survive — but a file written by a newer surrealctl is refused rather than migrated:

was written by a newer surrealctl (file version 2, this build understands 1).
Refusing to touch it — upgrade surrealctl, 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

• •

  Overview — the rest of the reference

• •

  SurrealDB CLI — for working with the data inside an instance