health

Check control-plane and compute-engine reachability; print each response as pretty JSON.

Syntax

delta-forge-cli health

Description

## Overview `health` probes both DeltaForge planes and prints their health responses. It is the first-line diagnostic when a session fails to start or queries return connection errors. ## Behavior - Sends a `GET /` health request to the control plane URL first, then to the compute engine URL. Each is probed independently. - Output is printed to stderr with the URL on one line and either the pretty-printed JSON response prefixed with `OK:` or an `UNAVAILABLE:` line with the underlying error message. - The command returns exit code 0 whether or not the endpoints are reachable. Operational checks that need to fail the shell on unreachable endpoints must parse stderr. - Authentication is attempted when credentials are explicit. When stdin is a TTY and credentials are missing, the inline credential prompt collects them before probing. The control-plane probe itself does not require authentication. - The control and compute URLs follow the standard resolution order: `--control-url` / `--compute-url` flags win, followed by `DF_CONTROL_URL` / `DF_COMPUTE_URL`, followed by profile values, followed by `http://localhost:3000` and `http://localhost:3031`. ## Compatibility - Health output JSON shape is defined by each plane's health handler; the CLI does not post-process the body, so downstream parsers can rely on the plane's documented schema. - This command is intentionally minimal. Deeper diagnostics (compute-node load, workspace affinity) belong in `/nodes` and `/context` slash commands inside the REPL.

Examples

# Use defaults from profile / env
delta-forge-cli health

# Explicit URLs override profile and env
delta-forge-cli --control-url https://control.prod:3000 --compute-url https://compute.prod:3031 health

# Probe against a named profile
delta-forge-cli --profile production health

# Exit code is 0 even when an endpoint is unavailable;
# parse stderr for 'UNAVAILABLE' in CI
delta-forge-cli health 2>health.log && grep -q UNAVAILABLE health.log && exit 1

Pitfalls

• `health` always exits 0, even when one or both planes are unreachable. CI checks that want to fail on unreachable services must grep stderr for `UNAVAILABLE` or use a per-plane probe through the HTTP API.
• The command prints all output to stderr, not stdout. Redirecting with `>` alone captures nothing; use `2>` or `2>&1` to capture health output.
• When `DF_COMPUTE_URL` is not set and no profile defines one, the compute probe targets `http://localhost:3031` regardless of which node the control plane would actually route queries to. A green compute probe on localhost does not prove the production worker pool is healthy.

See Also

• CLI_ENV_CONTROL_URL
• CLI_ENV_COMPUTE_URL
• CLI_FLAG_CONTROL_URL
• CLI_FLAG_COMPUTE_URL
• CLI_AUTH_FLOW