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.

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

Requires Node.js >= 22.16.

# 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"

• 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

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 mcp install                     # Add the MCP server to your AI agents
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.

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

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).

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

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.

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 login                                    # Interactive prompts
hdx auth login -a https://your-hyperdx.example \
    -e user@example.com -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.

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.

Adds the ClickStack MCP server to every supported agent it finds: Claude Code, Codex, Cursor, and VS Code. It asks for a personal access key or an organization API key with hidden input and checks it before changing any config, so the key stays out of shell history and agent chats.

npx @hyperdx/cli mcp install -a https://your-hyperdx.example

The key is stored in plain text in each agent's user config, which the command lists when it finishes. Running it again replaces the existing entry.

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"

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

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>

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

MIT