Config resolution order

For each setting the CLI resolves in this order: CLI flag -> environment variable -> profile value from config.toml -> built-in default. First non-None wins.

Syntax

flag > env > profile > default

Description

## Overview Every tunable setting in the CLI (control URL, compute URL, username, password, profile, output format, and display keys) is resolved through a deterministic four-step precedence chain. The chain runs independently per setting, so different settings on the same invocation can come from different layers. ## Behavior For each setting, the resolver consults these sources in order and returns the first non-None value: 1. **CLI flag**, such as `--control-url`, `--compute-url`, `--username`, `--password`, `--format`, or `--profile`. 2. **Environment variable**, such as `DF_CONTROL_URL`, `DF_COMPUTE_URL`, `DF_USERNAME`, `DF_PASSWORD`. 3. **Profile value** from `~/.deltaforge/config.toml`, chosen by `--profile` or `default_profile`. 4. **Built-in default**, for example `http://localhost:3000` for the control URL or `admin@deltaforge.local` for the username. Side effects tied to explicit values: - A profile or flag that sets `compute_url` marks it explicit, which disables Auto routing for that invocation. - A profile or flag that sets `username` marks credentials explicit, which suppresses the interactive shell login wizard. ## Resolution The chain is per setting, not per layer. `DF_CONTROL_URL=...` alongside `--compute-url=...` means the control URL comes from the environment and the compute URL comes from the flag. There is no concept of a layer "winning" across all settings at once.

Examples

# --control-url wins:
DF_CONTROL_URL=http://a delta-forge-cli --control-url http://b health
# effective: http://b

# profile wins when no flag/env:
# (profile dev has control_url=http://dev)
delta-forge-cli --profile dev health
# effective: http://dev

# default wins when nothing set:
delta-forge-cli health
# effective: http://localhost:3000

Pitfalls

• A stale `DF_CONTROL_URL` or `DF_PASSWORD` exported in the shell silently beats the profile value from `config.toml`. If a profile appears to be ignored, check the environment first with `env | grep DF_`.
• A profile value only applies when the earlier layers are empty. Setting `DF_CONTROL_URL` in your shell rc file permanently shadows the profile's `control_url` for every invocation from that shell.
• A malformed `config.toml` falls back to defaults with only a stderr warning. When that happens, profile resolution is disabled entirely and step 3 of the chain contributes nothing.

See Also

• CLI_CONFIG_FILE
• CLI_FLAG_PROFILE
• CLI_ENV_CONTROL_URL