@hyperdx/cli

Terminal UI and CLI for HyperDX — search, tail, chart, and query your logs, traces, and metrics without leaving the terminal.

The CLI talks to your HyperDX instance (Cloud or self-hosted) and runs the exact same query pipeline as the web app, so results always match what you see in the browser.

Install

npm install -g @hyperdx/cli    # installs the `hdx` binary
# or run without installing:
npx @hyperdx/cli --help

Requires Node.js >= 22.16.

Quickstart

# Sign in (interactive — prompts for app URL and credentials)
hdx auth login

# Launch the interactive TUI
hdx tui

# Chart error volume by service for the past 3 hours
hdx chart -s Logs --where 'SeverityText:error' --group-by ServiceName --since 3h

# Run raw SQL against ClickHouse
hdx query --connection-id "$CONN" --sql "SELECT count() FROM default.otel_logs"

Features

• Interactive TUI — search and live-tail events, inspect rows, and walk trace waterfalls with vim-style keybindings
• Trace waterfall — full span tree with correlated logs, span-level detail, and open-in-browser deep links
• Terminal charts — render saved dashboard tiles or ad-hoc charts (line, stacked bar, number, table, bar, pie) as ANSI output
• Raw SQL — query ClickHouse directly through the HyperDX proxy, in any ClickHouse output format
• Log pattern mining — cluster query results into Drain log patterns to summarize large result sets
• Alerts & dashboards — browse alerts (with trigger history) and dashboards from the TUI
• Multi-team support — kubectx-style team switching for users in multiple teams
• Agent-friendly — --json output on discovery commands, NDJSON streaming, documented exit codes, and colors stripped automatically when piping

Commands

hdx tui                             # Interactive TUI (search + live tail)
hdx chart -d <dashboard> [-t tile]  # Render dashboard tiles as ANSI charts
hdx chart -s <source> [--agg ...]   # Ad-hoc chart over a source
hdx chart --sql <query> -s <source> # Ad-hoc chart from raw SQL
hdx query --connection-id <id> --sql <query>  # Raw SQL to stdout
hdx sources                         # List data sources with table schemas
hdx connections                     # List ClickHouse connections
hdx dashboards                      # List dashboards with tile summaries
hdx auth login|status|logout        # Manage authentication
hdx team list|current|use <team>    # Switch between teams
hdx upload-sourcemaps               # Upload JS source maps

Every command accepts -a, --app-url <url> to point at a HyperDX instance. After hdx auth login, the URL is saved and the flag becomes optional. Run hdx <command> --help for full flag documentation.

hdx tui — Interactive TUI

The main event viewer: a searchable, live-tailing table of logs or traces with a detail panel, trace waterfall, pattern mining, alerts, and dashboards.

hdx tui                          # Pick a source interactively
hdx tui --source "Logs"          # Skip the source picker
hdx tui -q "level:error" -f      # Start with a search query, in follow mode

| Key | Action | | ------------- | ------------------------------------------ | | j / ↓ | Move selection down | | k / ↑ | Move selection up | | l / Enter | Expand row detail | | h / Esc | Close detail / blur search | | G / g | Jump to newest / oldest | | Ctrl+D/U | Page down / up | | / | Search (global in table, filter in detail) | | Tab | Cycle sources/searches or detail tabs | | Shift+Tab | Cycle backwards | | t | Edit time range in $EDITOR | | s | Edit SELECT clause in $EDITOR | | Shift+P | Show event patterns | | Shift+D | Show generated SQL | | f | Toggle follow mode (live tail) | | o | Open trace in browser | | w | Toggle line wrap | | Shift+A | Open alerts page | | d | Open dashboards page | | ? | Toggle help | | q | Quit |

The row detail panel has three tabs — Overview (structured OTel attributes), Column Values (every column of the row), and Trace (span waterfall with correlated logs, navigable with j/k).

hdx chart — Terminal charts

Render charts as terminal output. Designed for troubleshooting from the CLI (including by AI agents): visualize a metric, spot the spike, then narrow down with --where or hdx query. All modes run through the same renderChartConfig pipeline as the web dashboards.

Three modes:

# 1. Dashboard tiles — render saved tiles from a dashboard
hdx chart -d "Service Health"                       # All tiles, past 1h
hdx chart -d "Service Health" -t "P95 Latency" --since 24h

# 2. Ad-hoc builder — chart an aggregation over a source
hdx chart -s Logs --where 'SeverityText:error' --group-by ServiceName --since 3h
hdx chart -s Traces --agg quantile --level 0.95 --value Duration \
    --where 'ServiceName:api' --since 6h
hdx chart -s Logs --display bar --where 'SeverityText:error' --group-by ServiceName
hdx chart -s Metrics --metric-type sum --metric-name otelcol_exporter_sent_spans

# 3. Raw SQL — chart arbitrary queries with time macros
hdx chart -s Logs --sql "SELECT \$__timeInterval(TimestampTime) AS ts, count()
    FROM default.otel_logs WHERE \$__timeFilter(TimestampTime) GROUP BY ts ORDER BY ts"

• Display types (--display): line (default), stacked_bar, number, table, bar, pie
• Time ranges: --since 15m|1h|7d, or --from/--to with ISO 8601 (2026-07-01T00:00:00Z), dates (2026-07-01), or relative values (now-24h)
• SQL macros: $__timeFilter(col) expands to the selected range, $__timeInterval(col) buckets by the chart granularity
• Output: ANSI colors are stripped automatically when piping (override with --color always|never); --json emits raw rows + column metadata

hdx query — Raw SQL

Execute raw ClickHouse SQL through the HyperDX proxy. Output defaults to JSONEachRow (NDJSON — one JSON object per line), so results pipe cleanly into jq and friends. Any ClickHouse output format is accepted via --format (JSON, TabSeparated, CSV, ...).

CONN=$(hdx connections --json | jq -r '.[0].id')
hdx query --connection-id "$CONN" --sql "SELECT count() FROM default.otel_logs"
hdx query --connection-id "$CONN" --sql "SELECT * FROM default.otel_traces LIMIT 5"

Pattern mining (--patterns): cluster the result into templated log patterns using the Drain algorithm and emit one JSON object per pattern, sorted by count — useful for summarizing thousands of rows into a handful of templates:

hdx query --connection-id "$CONN" --patterns \
    --sql "SELECT Body FROM default.otel_logs LIMIT 10000" --body-column Body
# {"pattern":"connection <*> closed","count":4823,"sample":"connection 10.0.3.7 closed"}

Exit codes: 0 on success (empty stdout means zero rows), 1 on failure.

hdx sources / hdx connections / hdx dashboards — Discovery

List the data sources, ClickHouse connections, and dashboards available to your team. All three support --json for structured output.

hdx sources               # Sources with ClickHouse CREATE TABLE schemas
hdx sources --json        # Includes column expression mappings per source
hdx connections --json    # Connection IDs for `hdx query` / `hdx chart --sql`
hdx dashboards            # Dashboards + tile names for `hdx chart -d`

hdx auth — Authentication

hdx auth login                                    # Interactive prompts
hdx auth login -a https://your-hyperdx.example \
    -e [email protected] -p "$PASSWORD"            # Non-interactive (CI)
hdx auth status                                   # Who am I + active team
hdx auth logout

The session is saved to ~/.config/hyperdx/cli/session.json (mode 0600) and reused by all commands until it expires.

hdx team — Team switching

For users that belong to multiple teams (HyperDX Cloud / EE), switch the team that all commands are scoped to — kubectx-style:

hdx team list             # All teams, active one marked
hdx team current          # Print the active team
hdx team use "My Team"    # Switch by name or ID

The choice persists across CLI invocations. On single-team deployments these commands are effectively no-ops.

hdx upload-sourcemaps — Source maps

Upload JavaScript source maps to HyperDX for stack trace de-obfuscation. Run it in your build pipeline:

npx @hyperdx/cli upload-sourcemaps \
  --serviceKey "$HYPERDX_API_ACCESS_KEY" \
  --apiUrl "$HYPERDX_API_URL" \
  --path .next \
  --releaseId "$RELEASE_ID"

| Flag | Description | Default | | ------------------------ | ------------------------------------------------------ | ------- | | -k, --serviceKey <key> | HyperDX service account API key | | | -p, --path <dir> | Directory containing sourcemaps | . | | -u, --apiUrl <url> | HyperDX API URL (required for self-hosted deployments) | | | -rid, --releaseId <id> | Release ID to associate with the sourcemaps | | | -bp, --basePath <path> | Base path for the uploaded sourcemaps | | | --apiVersion <version> | API version: v1 (HyperDX V1 Cloud) or v2 (latest) | v1 |

Optionally, set the HYPERDX_SERVICE_KEY environment variable to avoid passing the --serviceKey flag.

For AI agents & scripting

The CLI is built to be driven by scripts and AI agents:

• hdx sources --json, hdx connections --json, hdx dashboards --json, and hdx team list --json emit structured output for discovery
• hdx query streams NDJSON by default and documents its exit-code contract (0 success, 1 failure — with "unknown connection" distinguished from "bad SQL" on stderr)
• hdx query --patterns compresses large result sets into a few templated patterns
• hdx chart --json returns the queried rows + column metadata instead of a rendered chart; ANSI colors are stripped automatically when stdout is not a TTY
• Non-interactive login: hdx auth login -a <url> -e <email> -p <password>

Links

• HyperDX repository
• ClickStack documentation
• Report an issue
• Contributing

License

MIT