d995b78c66
## Summary
Adds `packages/cli` (`@hyperdx/cli`) — a unified CLI for HyperDX that provides an interactive TUI for searching/tailing logs and traces, source map upload (migrated from `hyperdx-js`), and agent-friendly commands for programmatic access.
Ref: HDX-3919
Ref: HDX-3920
### CLI Commands
```
hdx tui -s <url> # Interactive TUI (main command)
hdx sources -s <url> # List sources with ClickHouse schemas
hdx sources -s <url> --json # JSON output for agents / scripts
hdx dashboards -s <url> # List dashboards with tile summaries
hdx dashboards -s <url> --json # JSON output for agents / scripts
hdx query --source "Logs" --sql "SELECT count() FROM default.otel_logs"
hdx upload-sourcemaps -k <key> # Upload source maps (ported from hyperdx-js)
hdx auth login -s <url> # Sign in (interactive or -e/-p flags)
hdx auth status # Show auth status
hdx auth logout # Clear saved session
```
### Key Features
**Interactive TUI (`hdx tui`)**
- Table view with dynamic columns derived from query results (percentage-based widths)
- Follow mode (live tail) enabled by default, auto-pauses when detail panel is open
- Vim-like keybindings: j/k navigation, G/g jump, Ctrl+D/U half-page scroll
- `/` for Lucene search, `s` to edit SELECT clause in `$EDITOR`, `t` to edit time range
- Tab to cycle between sources and saved searches
- `w` to toggle line wrap
**Detail Panel (3 tabs, full-screen with Ctrl+D/U scrolling)**
- **Overview** — Structured view: Top Level Attributes, Log/Span Attributes, Resource Attributes
- **Column Values** — Full `SELECT *` row data with `__hdx_*` aliased columns
- **Trace** — Waterfall chart (port of `DBTraceWaterfallChart` DAG builder) with correlated log events, j/k span navigation, inverse highlight, Event Details section
**Agent-friendly commands**
- `hdx sources --json` — Full source metadata with ClickHouse `CREATE TABLE` DDL, expression mappings, and correlated source IDs. Detailed `--help` describes the JSON schema for LLM consumption. Schema queries run in parallel.
- `hdx dashboards --json` — Dashboard metadata with simplified tile summaries (name, type, source, sql). Resolves source names for human-readable output.
- `hdx query --source <name> --sql <query>` — Raw SQL execution against any source's ClickHouse connection. Supports `--format` for ClickHouse output formats (JSON, JSONEachRow, CSV, etc.).
**Source map upload (`hdx upload-sourcemaps`)**
- Ported from `hyperdx-js/packages/cli` to consolidate on a single `@hyperdx/cli` package
- Authenticates via service account API key (`-k` / `HYPERDX_SERVICE_KEY` env var)
- Globs `.js` and `.js.map` files, handles Next.js route groups
- Uploads to presigned URLs in parallel with retry (3 attempts) and progress
- Modernized: native `fetch` (Node 22+), ESM-compatible, proper TypeScript types
### Architecture
```
packages/cli/
├── src/
│ ├── cli.tsx # Commander CLI: tui, sources, dashboards, query,
│ │ # upload-sourcemaps, auth
│ ├── App.tsx # Ink app shell (login → source picker → EventViewer)
│ ├── sourcemaps.ts # Source map upload logic (ported from hyperdx-js)
│ ├── api/
│ │ ├── client.ts # ApiClient + ProxyClickhouseClient
│ │ └── eventQuery.ts # Query builders (renderChartConfig, raw SQL)
│ ├── components/
│ │ ├── EventViewer/ # Main TUI (9 files)
│ │ │ ├── EventViewer.tsx # Orchestrator (state, hooks, render shell)
│ │ │ ├── types.ts # Shared types & constants
│ │ │ ├── utils.ts # Row formatting functions
│ │ │ ├── SubComponents.tsx # Header, TabBar, SearchBar, Footer, HelpScreen, TableHeader
│ │ │ ├── TableView.tsx # Table rows rendering
│ │ │ ├── DetailPanel.tsx # Detail panel (overview/columns/trace tabs)
│ │ │ ├── useEventData.ts # Data fetching hook
│ │ │ └── useKeybindings.ts # Input handler hook
│ │ ├── TraceWaterfall/ # Trace chart (6 files)
│ │ │ ├── TraceWaterfall.tsx # Orchestrator + render
│ │ │ ├── types.ts # SpanRow, SpanNode, props
│ │ │ ├── utils.ts # Duration/status/bar helpers
│ │ │ ├── buildTree.ts # DAG builder (port of DBTraceWaterfallChart)
│ │ │ └── useTraceData.ts # Data fetching hook
│ │ ├── RowOverview.tsx
│ │ ├── ColumnValues.tsx
│ │ ├── LoginForm.tsx
│ │ └── SourcePicker.tsx
│ ├── shared/ # Ported from packages/app (@source annotated)
│ └── utils/ # Config, editor, log silencing
├── AGENTS.md
├── CONTRIBUTING.md
└── README.md
```
### Tech Stack
- **Ink v6.8.0** (React 19 for terminals) + Commander.js
- **@clickhouse/client** via ProxyClickhouseClient (routes through `/clickhouse-proxy`)
- **@hyperdx/common-utils** for query generation (`renderChartConfig`, `chSqlToAliasMap`)
- **glob v13** for source map file discovery
- **tsup** for bundling (all deps bundled via `noExternal: [/.*/]`, zero runtime deps)
- **Bun 1.3.11** for standalone binary compilation
- Session stored at `~/.config/hyperdx/cli/session.json`
### CI/CD (`release.yml`)
- CLI binaries compiled for macOS ARM64, macOS x64, and Linux x64
- GitHub Release created with download instructions
- Version-change gate: skips release if `cli-v{version}` tag already exists
- `softprops/action-gh-release` pinned to full SHA (v2.6.1) for supply chain safety
- Bun pinned to `1.3.11` for reproducible builds
- npm publishing handled by changesets
### Keybindings
| Key | Action |
|---|---|
| `j/k` | Navigate rows (or spans in Trace tab) |
| `l/Enter` | Expand row detail |
| `h/Esc` | Close detail / blur search |
| `G/g` | Jump to newest/oldest |
| `Ctrl+D/U` | Scroll half-page (table, detail panels, Event Details) |
| `/` | Search (global or detail filter) |
| `Tab` | Cycle sources/searches or detail tabs |
| `s` | Edit SELECT clause in $EDITOR |
| `t` | Edit time range in $EDITOR |
| `f` | Toggle follow mode (live tail) |
| `w` | Toggle line wrap |
| `?` | Help screen |
### Demo
#### Main Search View
<img width="1004" height="1014" alt="image" src="https://github.com/user-attachments/assets/bb6a7f00-38c9-4281-9915-c71b65d852f8" />
#### Event Details Overview
<img width="1003" height="1024" alt="image" src="https://github.com/user-attachments/assets/57025fa5-fddb-452a-9320-93465538d5b2" />
#### Trace Waterfall
<img width="1004" height="1029" alt="image" src="https://github.com/user-attachments/assets/3443c898-ea0d-47f3-acc5-edb7cdd31946" />
|
||
|---|---|---|
| .changeset | ||
| .claude | ||
| .config | ||
| .cursor | ||
| .github | ||
| .husky | ||
| .opencode/commands | ||
| .vex | ||
| .vscode | ||
| .yarn/releases | ||
| agent_docs | ||
| docker | ||
| docs/assets | ||
| packages | ||
| proxy | ||
| scripts | ||
| smoke-tests/otel-collector | ||
| .env | ||
| .gitattributes | ||
| .gitignore | ||
| .kodiak.toml | ||
| .mcp.json | ||
| .nvmrc | ||
| .prettierignore | ||
| .prettierrc | ||
| .yarnrc.yml | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| CONTRIBUTING.md | ||
| DEPLOY.md | ||
| docker-compose.ci.yml | ||
| docker-compose.dev.yml | ||
| docker-compose.yml | ||
| knip.json | ||
| LICENSE | ||
| LOCAL.md | ||
| Makefile | ||
| nx.json | ||
| package.json | ||
| README.md | ||
| tsconfig.base.json | ||
| version.sh | ||
| yarn.lock | ||
HyperDX
HyperDX, a core component of ClickStack, helps engineers quickly figure out why production is broken by making it easy to search & visualize logs and traces on top of any ClickHouse cluster (imagine Kibana, for ClickHouse).
Documentation • Chat on Discord • Live Demo • Bug Reports • Contributing • Website
- 🕵️ Correlate/search logs, metrics, session replays and traces all in one place
- 📝 Schema agnostic, works on top of your existing ClickHouse schema
- 🔥 Blazing fast searches & visualizations optimized for ClickHouse
- 🔍 Intuitive full-text search and property search syntax (ex.
level:err), SQL optional! - 📊 Analyze trends in anomalies with event deltas
- 🔔 Set up alerts in just a few clicks
- 📈 Dashboard high cardinality events without a complex query language
{Native JSON string querying- ⚡ Live tail logs and traces to always get the freshest events
- 🔭 OpenTelemetry supported out of the box
- ⏱️ Monitor health and performance from HTTP requests to DB queries (APM)
Spinning Up HyperDX
HyperDX can be deployed as part of ClickStack, which includes ClickHouse, HyperDX, OpenTelemetry Collector and MongoDB.
docker run -p 8080:8080 -p 4317:4317 -p 4318:4318 docker.hyperdx.io/hyperdx/hyperdx-all-in-one
Afterwards, you can visit http://localhost:8080 to access the HyperDX UI.
If you already have an existing ClickHouse instance, want to use a single container locally, or are looking for production deployment instructions, you can view the different deployment options in our deployment docs.
If your server is behind a firewall, you'll need to open/forward port 8080, 8000 and 4318 on your firewall for the UI, API and OTel collector respectively.
We recommend at least 4GB of RAM and 2 cores for testing.
Hosted ClickHouse Cloud
You can also deploy HyperDX with ClickHouse Cloud, you can sign up for free and get started in just minutes.
Instrumenting Your App
To get logs, metrics, traces, session replay, etc into HyperDX, you'll need to instrument your app to collect and send telemetry data over to your HyperDX instance.
We provide a set of SDKs and integration options to make it easier to get started with HyperDX, such as Browser, Node.js, and Python
You can find the full list in our docs.
OpenTelemetry
Additionally, HyperDX is compatible with OpenTelemetry, a vendor-neutral standard for instrumenting your application backed by CNCF. Supported languages/platforms include:
- Kubernetes
- Javascript
- Python
- Java
- Go
- Ruby
- PHP
- .NET
- Elixir
- Rust
(Full list here)
Once HyperDX is running, you can point your OpenTelemetry SDK to the
OpenTelemetry collector spun up at http://localhost:4318.
Contributing
We welcome all contributions! There's many ways to contribute to the project, including but not limited to:
- Opening a PR (Contribution Guide)
- Submitting feature requests or bugs
- Improving our product or contribution documentation
- Voting on open issues or contributing use cases to a feature request
Motivation
Our mission is to help engineers ship reliable software. To enable that, we believe every engineer needs to be able to easily leverage production telemetry to quickly solve burning production issues.
However, in our experience, the existing tools we've used tend to fall short in a few ways:
- They're expensive, and the pricing has failed to scale with TBs of telemetry becoming the norm, leading to teams aggressively cutting the amount of data they can collect.
- They're hard to use, requiring full-time SREs to set up, and domain experts to use confidently.
- They requiring hopping from tool to tool (logs, session replay, APM, exceptions, etc.) to stitch together the clues yourself.
We hope you give HyperDX in ClickStack a try and let us know how we're doing!
Contact
HyperDX Usage Data
HyperDX collects anonymized usage data for open source deployments. This data
supports our mission for observability to be available to any team and helps
support our open source product run in a variety of different environments.
While we hope you will continue to support our mission in this way, you may opt
out of usage data collection by setting the USAGE_STATS_ENABLED environment
variable to false. Thank you for supporting the development of HyperDX!