CLI Reference

Reference index of 90 cli reference in DeltaForge: complete catalogue grouped by category, each linking to detailed syntax and examples.

authentication

• Authentication flowAt launch the CLI POSTs credentials to the control plane's /login endpoint. On success it receives...
• Inline credential promptStdin-based fallback prompt used by non-REPL commands (query, run, auth, health, demo-test) when credentials...
• TUI login wizardFull-screen terminal UI login screen. Used when entering the interactive REPL and credentials are not...

automation

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

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...
• 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...
• Auto routing (default)Default mode. Every SQL call routes through the control plane's /nodes/recommend endpoint. The control plane...
• Explicit compute URLSetting --compute-url or DF_COMPUTE_URL pins a specific URL and disables Auto routing. The pinned URL is...
• Pinned node (/use-node)Inside the shell, /use-node <NAME> resolves a node display name against /list-compute-nodes and pins it for...

configuration

• Config resolution orderFor each setting the CLI resolves in this order: CLI flag -> environment variable -> profile value from...
• Filesystem pathsConfig directory: `~/.deltaforge/`. Config file: `config.toml`. History: `history` (1000 entries). Sessions...
• Named profilesA profile bundles control_url, compute_url, and username under a single name. Select with --profile...
• [display] settingsDisplay preferences: `max_rows` (default 100), `compact` (default false), `timing` (default true). Apply to...
• ~/.deltaforge/config.tomlTOML configuration file with profiles, default profile, and display preferences. Optional; the CLI runs...

demo-runner

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

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...
• DF_PASSWORDPassword for control-plane authentication. Presence marks credentials as explicit (skips interactive...
• 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...
• --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...
• --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...
• --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...

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...
• JSON outputStructured pretty-printed JSON with `columns`, `rows` (array of objects keyed by column name), `row_count`...
• Table output (default)Unicode-bordered tables with bold cyan headers, right-aligned numerics, dim-italic NULLs, and a row-count...

repl-features

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

safety

• Dangerous-SQL detectionBefore executing SQL, the CLI performs a keyword-based scan (uppercased, whitespace-split) to detect...

script-execution

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

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...
• /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...
• /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.