CLI Reference

The command-line client: authentication, configuration, scripting, the REPL, and every global flag.

Authentication

• Authentication flowAt launch the CLI POSTs credentials to the control plane's /login endpoint. On success it receives access_token (short-lived), refresh_token...
• Inline credential promptStdin-based fallback prompt used by non-REPL commands (query, run, auth, health, demo-test) when credentials were not supplied via flag/env/profile...
• TUI login wizardFull-screen terminal UI login screen. Used when entering the interactive REPL and credentials are not explicit. Tab moves focus; Enter submits; Esc...

Automation

• CI/CD patternIn CI: set DF_CONTROL_URL and DF_PASSWORD as secrets, run `delta-forge-cli --profile ci run <FILE>`. Exit 0 = success; non-zero = fail the job.
• Error handling for automationUse exit codes to branch: 0=success, 1=SQL/auth/parse error, 2=client init error. Capture stderr for error messages; stdout carries only result data...
• Export tokens for downstream tools`delta-forge-cli auth` prints `session_token=...`, `access_token=...`, and `refresh_token=...` as key=value lines on stdout (one per line). Parse...
• Headless script executionRun a multi-statement SQL script non-interactively with explicit credentials and a named profile. Exit code drives CI pass/fail.
• Non-TTY inline prompt fallbackWhen stdin or stdout is not a TTY (CI runners, `ssh -T`, Docker without `-t`, unattended job steps), any interactive surface the CLI would otherwise...
• Parsing JSON output with jqWith --format json the schema is `{ columns: string[], rows: Array<Record<string, string|null>>, row_count: number, execution_time_ms: number }`...
• Piping SQL from stdinWhen stdin is not a TTY, the default invocation reads and executes stdin as a multi-statement script. Ideal for generating SQL on the fly and piping...

Commands

• authAuthenticate against the control plane and print the resulting access, session, and refresh tokens to stdout.
• delta-forge-cli (interactive REPL)Launch the interactive shell when stdin is a TTY; execute piped SQL as a script when stdin is not a TTY.
• demo-testEnd-to-end demo-test runner: provisions a demo dataset via the control plane, runs setup/queries/cleanup SQL, emits a JSON report.
• healthCheck control-plane and compute-engine reachability; print each response as pretty JSON.
• planShow the logical or physical execution plan for a SQL statement without scanning any data.
• queryExecute a single SQL statement and print the result set.
• runExecute a multi-statement SQL script file with variable substitution and per-statement progress reporting.

Compute Routing

• /nodes/recommend APIControl-plane endpoint consulted by Auto routing on every SQL call. Takes the current workspace/session context and returns a ranked list of healthy...
• Auto routing (default)Default mode. Every SQL call routes through the control plane's /nodes/recommend endpoint. The control plane picks the best worker based on load...
• Explicit compute URLSetting --compute-url or DF_COMPUTE_URL pins a specific URL and disables Auto routing. The pinned URL is used for every query until /use-node auto...
• Pinned node (/use-node)Inside the shell, /use-node <NAME> resolves a node display name against /list-compute-nodes and pins it for subsequent queries. Ctrl+N opens the...

Configuration

• [display] settingsDisplay preferences: `max_rows` (default 100), `compact` (default false), `timing` (default true). Apply to both the REPL and non-interactive...
• Config resolution orderFor each setting the CLI resolves in this order: CLI flag -> environment variable -> profile value from config.toml -> built-in default. First...
• Filesystem pathsConfig directory: `~/.deltaforge/`. Config file: `config.toml`. History: `history` (1000 entries). Sessions: `sessions/<YYYYMMDD-HHMMSS>.jsonl`.
• Named profilesA profile bundles control_url, compute_url, and username under a single name. Select with --profile. default_profile sets the fallback when...
• ~/.deltaforge/config.tomlTOML configuration file with profiles, default profile, and display preferences. Optional; the CLI runs without it using built-in defaults.

Demo Runner

• --drop-schema / --drop-zoneOpt-in destructive flags for the cleanup phase. Without these, cleanup runs only the demo's teardown SQL; with them it also drops the created schema...
• --local <DIR>Override SQL file location with a local directory. Data paths still come from the provisioned environment. Use this for iterative debugging of...
• --phase setup|queries|cleanup|allSelect which phase(s) to run. `all` is the default. Useful for iterative debugging: provision once, then re-run just `queries` against the...
• Demo test runner overview`demo-test` is an end-to-end test harness. It provisions demo data via the control plane /provision-demo API, runs setup + queries + cleanup SQL...
• Demo variable injectionBefore executing any demo SQL, three variables are injected: `{{zone_name}}` (target zone), `{{data_path}}` (zone-relative path to provisioned...
• JSON report outputOn completion, demo-test emits a structured JSON report on stdout with demo identity, per-phase status, per-statement details, timings, and errors...

Environment Variables

• DF_COMPUTE_URLPinned compute-node URL. Presence disables Auto routing. Default: http://localhost:3031.
• DF_CONTROL_URLControl-plane base URL. Overridden by --control-url; overrides profile. Default: http://localhost:3000.
• DF_HTTP_TIMEOUT_SECSHTTP client timeout in seconds for all control-plane and compute-engine requests. Set to 0 or `none` to disable the timeout entirely. Default: 1800...
• DF_PASSWORDPassword for control-plane authentication. Presence marks credentials as explicit (skips interactive prompt). Default: admin123 (for local dev only).
• DF_USERNAMEUsername for control-plane authentication. Default: admin@deltaforge.local.

Global Flags

• --classicUse the legacy single-line reedline REPL instead of the interactive shell. Non-interactive subcommands are unaffected.
• --compute-urlPin an explicit compute-node URL, disabling Auto routing via the control plane's /nodes/recommend endpoint.
• --control-urlOverride the control-plane base URL for this invocation. Highest precedence (wins over env and profile).
• --force / -ySkip confirmation prompts for dangerous SQL (DROP, DELETE without WHERE, UPDATE without WHERE, TRUNCATE).
• --formatSelect output format for non-interactive commands. One of `table` (default), `compact`, `json`.
• --nodeCompute node display name or entity_ref, resolved via control plane /list-compute-nodes and pinned for the session.
• --passwordPassword for control-plane authentication. Presence marks credentials as explicit (skips interactive prompt).
• --profile / -pSelect a named profile from `~/.deltaforge/config.toml`. Overrides `default_profile`.
• --resumeRehydrate the scrollback from a previous session JSONL file under `~/.deltaforge/sessions/`. With no value loads the most recent file; with an...
• --username / -uUsername for control-plane authentication. Sets the `credentials_explicit` flag so the TUI wizard is skipped.

Keybindings

• Keyboard shortcutsKeyboard shortcuts available in the default interactive REPL. Covers submission (Enter, Ctrl+Enter, Shift+Enter), history (Up/Down, Ctrl+R)...

Output Formats

• Compact outputBorderless output with two-space indent. Intended for narrow terminals and log-friendly capture.
• DML result lineFor statements with no result set (INSERT/UPDATE/DELETE/MERGE/DDL), prints a single indented line with a green checkmark, the engine's message, and...
• JSON outputStructured pretty-printed JSON with `columns`, `rows` (array of objects keyed by column name), `row_count`, and `execution_time_ms`. Stable schema...
• Table output (default)Unicode-bordered tables with bold cyan headers, right-aligned numerics, dim-italic NULLs, and a row-count footer.

REPL Features

• Completions popupFloating popup that ranks candidates from the identifier cache and the SQL keyword list against the word under the cursor. Up/Down navigates; Tab or...
• History file`--classic` persists submissions to `~/.deltaforge/history` via reedline (1000-entry file-backed ring). The interactive shell maintains an in-memory...
• looks_complete heuristicDecides whether Enter submits the buffer or inserts a newline. Slash/colon commands are always complete; SQL is complete only when the trimmed...
• Session JSONLOn exit, the interactive shell flushes its scrollback to `~/.deltaforge/sessions/<YYYYMMDD-HHMMSS>.jsonl`. One JSON object per completed turn...
• Slash-command menuFloating menu that lists the top-scoring slash commands when the input starts with `/` or `:`. Up/Down moves the highlight, Tab completes...

Safety

• Dangerous-SQL detectionBefore executing SQL, the CLI performs a keyword-based scan (uppercased, whitespace-split) to detect destructive operations. A match prompts for...

Script Execution

• -D variable substitution`-D key=value` injects VALUE wherever `{{key}}` appears in the script. Substitution is textual (no type coercion). Repeat -D for multiple variables.
• Exit codes0 = success. 1 = execution error (query failure, auth failure, parse error). 2 = fatal client-init error (bad URL, can't construct HTTP client).
• Per-statement progress reportingDuring `run`, each statement prints `[N/TOTAL] <preview> ... <message> (<elapsed>ms)` on stderr. The preview is the first non-empty, non-comment...
• Piped SQL from stdinWhen stdin is not a TTY, the default invocation reads the entire stdin as a multi-statement SQL script and executes it. Output uses --format.
• Statement splittingSemicolon-terminated statement splitter that respects single-quoted string literals and `--` line comments. Implemented in...

Slash Commands

• /classifyClassify each statement in a script (DML, DDL, MAINTENANCE, PIPELINE, etc.). Offline AST walk.
• /clearClear scrollback. Aliases: /cls, Ctrl+L.
• /cmdRender the full reference page for a single SQL command.
• /columnsColumn list (name, type, nullable, position) for a table.
• /contextBootstrap context: active workspace, zones, compute, recent pipelines. Useful as the first command after login.
• /demoOpen a runnable demo by id (from the demo gallery). Shows the provision manifest + the queries you can run.
• /describeCatalog describe for any entity (table, view, schema, zone, workspace, pipeline). Routes through the control-plane DESCRIBE endpoint.
• /docsFull-text search the embedded documentation (SQL commands, functions, operators, data types, CLI reference).
• /downstreamDownstream lineage only: every consumer of this table.
• /explain-sqlPlain-English explanation of what the SQL does. Offline.
• /extract-tablesList every table reference in the SQL (fully-qualified where possible). Offline AST walk.
• /formatReformat SQL: keywords uppercased, canonical indentation. Pure string rewrite; offline.
• /helpShow the interactive help card listing every slash command, its argument shape, and a one-line summary.
• /lineageFetch both upstream and downstream lineage for a table (columns + pipelines).
• /lineage-sqlExtract script-level inbound (sources) and outbound (targets) tables from a SQL snippet. Offline.
• /nodesList compute nodes with status, load, workspace affinity, and a click-through to pin each one.
• /openOpen item N of the last result (table row, node entry, pipeline, etc.) and render its detail card.
• /pipeline-statusPipeline health + recent errors. With no argument, shows every pipeline; with a name, drills into one.
• /quitExit the CLI. Persists the scrollback to ~/.deltaforge/sessions/.
• /schemasList schemas, optionally filtered by zone.
• /table-historyDelta transaction history (versions, timestamps, operation, operator).
• /table-statsRow count and size stats for a table.
• /upstreamUpstream lineage only: every table this one depends on.
• /use-nodePin a compute node for the session (or pass `auto` to re-enable control-plane /nodes/recommend routing).
• /validateParse SQL and report syntax errors with line:col positions. Offline - no control-plane round-trip.
• /workspaceWorkspace overview: zones, pipelines, schedules, compute nodes.
• /zonesList all zones.