DF_CONTROL_URL

Control-plane base URL. Overridden by --control-url; overrides profile. Default: http://localhost:3000.

Syntax

DF_CONTROL_URL=<URL>

Description

## Overview `DF_CONTROL_URL` is the base URL of the DeltaForge control plane that the CLI talks to for authentication, catalog lookups, compute-node discovery, and workspace operations. It is read once by `CliConfig::from_env` at process startup. The value becomes the default for `--control-url` and for any subcommand that needs a control-plane endpoint. ## Behavior - Read by `std::env::var("DF_CONTROL_URL")` at CLI startup. Not re-read during a running session. - Default when unset and no profile is loaded: `http://localhost:3000`. - A value of `None` at this layer lets the profile (`~/.deltaforge/config.toml`) supply the URL; otherwise the built-in default applies. - Overridden at runtime by `--control-url`. Overrides any `control_url` set in the active profile. - URL must include scheme (`http://` or `https://`). A bare hostname causes the reqwest client constructor to fail, which surfaces as exit code `2`. ## Resolution - `--control-url` flag (highest) - `DF_CONTROL_URL` - `control_url` in the active profile of `~/.deltaforge/config.toml` - Built-in default `http://localhost:3000` (lowest)

Examples

# One-shot override for a single invocation
DF_CONTROL_URL=https://control.prod.example.com delta-forge-cli health

# Persist for the current shell session
export DF_CONTROL_URL=https://control.prod.example.com

# Read from a password manager so the URL is not in shell history
export DF_CONTROL_URL=$(pass show deltaforge/prod/control-url)
delta-forge-cli list workspaces

# GitHub Actions workflow step
- name: Run DeltaForge migration
  env:
    DF_CONTROL_URL: ${{ secrets.DF_CONTROL_URL }}
    DF_USERNAME: ${{ secrets.DF_USERNAME }}
    DF_PASSWORD: ${{ secrets.DF_PASSWORD }}
  run: delta-forge-cli run migrations/001_init.sql

Pitfalls

• The env var is captured once at process start. Exporting a new value in the same shell after `delta-forge-cli` is already running has no effect; exit and relaunch.
• An active profile still loses to this env var. If the CLI appears to ignore a profile's `control_url`, check for a leftover `DF_CONTROL_URL` export in the shell or in parent process environment.

See Also

• CLI_FLAG_CONTROL_URL
• CLI_RESOLUTION_ORDER