Skip to content

Latest commit

 

History

History

cli

README.md

@hyperdx/cli

npm version License: MIT

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

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

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 mcp install — Connect AI agents

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.

If the key belongs to more than one team, it asks which teams to add a server for (Enter keeps the default team). Picking several adds one entry per team, named <name>-<team>. If it finds more than one agent, it asks which to set up (Enter keeps all of them).

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.

The entry is named clickstack. To keep more than one ClickStack instance side by side, give each its own name:

npx @hyperdx/cli mcp install -a https://staging.example --name clickstack-staging

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

License

MIT