Elgato_dark/hyperdx
1
0
Fork 0
mirror of https://github.com/hyperdxio/hyperdx synced 2026-04-21 13:37:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6
hyperdx/packages/cli/package.json

50 lines
1.3 KiB
JSON
Raw Normal View History

[HDX-3919] Add @hyperdx/cli package — terminal TUI, source map upload, and agent-friendly commands (#2043) ## 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" />
2026-04-09 20:21:34 +00:00
{
"name": "@hyperdx/cli",
Release HyperDX (#2094) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-04-10 18:08:49 +00:00
"version": "0.2.1",
[HDX-3919] Add @hyperdx/cli package — terminal TUI, source map upload, and agent-friendly commands (#2043) ## 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" />
2026-04-09 20:21:34 +00:00
"license": "MIT",
"type": "module",
"publishConfig": {
"access": "public"
},
"bin": {
"hdx": "./dist/cli.js"
},
"files": [
"dist/*"
],
"engines": {
"node": ">=22.16.0",
"bun": "1.3.11"
},
"scripts": {
"dev": "tsx src/cli.tsx",
"build": "tsup",
"prepublishOnly": "yarn build",
"compile": "bun build src/cli.tsx --compile --outfile dist/hdx",
"compile:linux": "bun build src/cli.tsx --compile --target=bun-linux-x64 --outfile dist/hdx-linux-x64",
"compile:macos": "bun build src/cli.tsx --compile --target=bun-darwin-arm64 --outfile dist/hdx-darwin-arm64",
"compile:macos-x64": "bun build src/cli.tsx --compile --target=bun-darwin-x64 --outfile dist/hdx-darwin-x64"
},
"devDependencies": {
"@clickhouse/client": "^1.12.1",
"@clickhouse/client-common": "^1.12.1",
Release HyperDX (#2060) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-04-10 00:33:14 +00:00
"@hyperdx/common-utils": "^0.17.1",
[HDX-3919] Add @hyperdx/cli package — terminal TUI, source map upload, and agent-friendly commands (#2043) ## 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" />
2026-04-09 20:21:34 +00:00
"@types/crypto-js": "^4.2.2",
"@types/react": "^19.0.0",
"@types/sqlstring": "^2.3.2",
"chalk": "^5.3.0",
"commander": "^12.1.0",
"crypto-js": "^4.2.0",
"glob": "^13.0.6",
"ink": "6.8.0",
"ink-spinner": "^5.0.0",
"ink-text-input": "^6.0.0",
"react": "^19.0.0",
"react-devtools-core": "^7.0.1",
"sqlstring": "^2.3.3",
"tsup": "^8.4.0",
"tsx": "^4.19.0",
"typescript": "^5.9.3"
}
}
Reference in a new issue Copy permalink