~/.deltaforge/config.toml

TOML configuration file with profiles, default profile, and display preferences. Optional; the CLI runs without it using built-in defaults.

Category: configuration

Syntax

[profiles.<name>]
control_url = "..."
compute_url = "..."
username = "..."

[display]
max_rows = 100
compact = false
timing = true

Description

## Overview `~/.deltaforge/config.toml` is the single on-disk configuration file for the CLI. It is optional: the CLI boots on built-in defaults (control plane at `http://localhost:3000`, Auto compute routing, username `admin@deltaforge.local`) when the file is absent. When present, it contributes three kinds of settings, profiles (groups of endpoint and identity values), a `default_profile` pointer, and a `[display]` block of rendering preferences. ## Behavior - The file is read once at startup from `~/.deltaforge/config.toml`. The CLI does not watch or reload it mid-process. - If the file exists but fails to parse, a warning is written to stderr and the CLI continues with built-in defaults. It does not abort. - `default_profile` selects the active profile when `--profile` is not passed. If neither `--profile` nor `default_profile` is set, no profile is applied and only flags, environment variables, and built-in defaults contribute to the effective configuration. - Passwords are never stored in this file. The profile schema has no `password` key. Credentials come from `--password`, `DF_PASSWORD`, an interactive prompt, or the built-in default. - The `[display]` block applies uniformly to the REPL, `query`, `run`, and shell-execution output. Each key has a documented default, so missing keys do not produce errors. ## Resolution For any setting that can come from the file, per-setting resolution order is: CLI flag, then environment variable, then profile value from this file, then built-in default. The first non-None wins. See `CLI_RESOLUTION_ORDER` for the full matrix.

Parameters

Name	Type	Description
`default_profile`		Name of the profile used when --profile is not passed.
`profiles.<name>.control_url`		Control plane base URL for this profile.
`profiles.<name>.compute_url`		Explicit compute URL for this profile. Presence disables Auto routing.
`profiles.<name>.username`		Control-plane username. Presence marks credentials as explicit.
`display.max_rows`		Maximum rows to render per result table.
`display.compact`		Default to compact output mode.
`display.timing`		Show elapsed-ms footer on every query.

Examples

default_profile = "dev"

[profiles.dev]
control_url = "http://localhost:3000"
compute_url = "http://localhost:3031"
username = "admin@deltaforge.local"

[profiles.production]
control_url = "https://control.company.com"
compute_url = "https://compute.company.com"
username = "engineer@company.com"

[display]
max_rows = 200
compact = false
timing = true

Pitfalls

A typo or invalid TOML in `config.toml` falls back silently to defaults. Scripts that assumed the file would apply may suddenly target `http://localhost:3000`. Check stderr for the parse warning if an expected profile does not take effect.
Profiles cannot store a password. Non-interactive automation that uses `--profile` must also provide `DF_PASSWORD` or `--password`, otherwise credential resolution falls through to the built-in default (or fails in a non-TTY context).
Setting `compute_url` on a profile pins compute to that URL and disables Auto routing for every invocation that uses the profile. Omit the key if you want the control plane to pick a healthy node per request.