# config Reference for surrealctl config — listing, reading, setting and clearing configuration values, printing the file path, and opening it in an editor. `surrealctl config` reads and writes the CLI's own configuration file. Nothing here sends a request: the file never leaves the machine. surrealctl config [OPTIONS] | 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`, `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](/docs/reference/cli/surrealctl/global-flags.md#the-precedence-chain). | Key | Type | Description | Outranked by | | --- | --- | --- | --- | | `org` | Text | Default organisation for this profile | `SURREALCTL_ORG` | | `api` | URL | Base URL of the SurrealDB API | `SURREALCTL_API` | | `json` | Boolean | Always emit machine-readable JSON | `SURREALCTL_JSON` | | `plain` | Boolean | Always disable tables, spinners and relative times | `SURREALCTL_PLAIN` | | `surreal_binary` | Text | Path to the `surreal` binary for `sql`, `import` and `export` | `SURREALCTL_SURREAL_BINARY` | The persisted context — what [`org use`](/docs/reference/cli/surrealctl/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. ## surrealctl config list {#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](/docs/reference/cli/surrealctl/output-and-exit-codes.md#list-presentation-flags). Column ids are `key`, `value`, `set` and `description`, with `kind` under `--wide`. ```bash surrealctl 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 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 {#config-get} Show one configuration value. surrealctl config get [OPTIONS] ", "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 "$(surrealctl config get org)" ]` and `wc -l` agree with each other. ```bash ORG=$(surrealctl config get org) ``` ```bash title="Branch on whether a key is set" 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 {#config-set} Set a configuration value. surrealctl config set [OPTIONS] ", "required": true, "description": "The configuration key." }, { "name": "", "required": true, "description": "The value to store." } ]} /> This command has no options of its own. ```bash title="Always emit JSON from this profile" surrealctl config set json true ``` ```bash title="Point at a specific surreal build" surrealctl config set surreal_binary /opt/surrealdb/3.2.4/surreal ``` ```bash title="Configure a second profile" 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: ```text 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 {#config-unset} Clear a configuration value. surrealctl config unset [OPTIONS] ", "required": true, "description": "The configuration key." } ]} /> This command has no options of its own. ```bash 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 {#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. ```bash surrealctl config path ``` ```text title="Output" /Users/ana/.config/surrealctl/config.toml ``` ```bash title="Back the file up before editing it" cp "$(surrealctl config path)" "$(surrealctl config path).bak" ``` `credentials.json` lives beside it in the same directory. See [credential storage](/docs/reference/cli/surrealctl/authentication.md#where-credentials-are-stored) for how that directory is chosen. ## surrealctl config edit {#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. ```bash surrealctl config edit ``` The file is opened with `$EDITOR`. Editing it by hand is supported — [`config list`](#config-list) will show whatever you wrote, and unknown keys survive — but a file written by a newer `surrealctl` is refused rather than migrated: ```text 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](/docs/reference/cli/surrealctl/global-flags.md) — the flags and environment variables these keys sit beneath - [`context` commands](/docs/reference/cli/surrealctl/commands/context.md) — switching between profiles - [`org use`](/docs/reference/cli/surrealctl/commands/org.md#org-use) — remembering an organisation within a profile - [Authentication](/docs/reference/cli/surrealctl/authentication.md#where-credentials-are-stored) — the credential file beside this one - [Overview](/docs/reference/cli/surrealctl/overview.md) — the rest of the reference - [SurrealDB CLI](/docs/reference/cli/surrealdb-cli/overview.md) — for working with the data inside an instance