### Install Dependencies and Setup Hooks

Source: https://github.com/hyperdxio/hyperdx/blob/main/agent_docs/development.md

Run this command to install project dependencies and set up necessary development hooks.

```bash
yarn setup
```

--------------------------------

### Install Dependencies and Start Development Server

Source: https://github.com/hyperdxio/hyperdx/blob/main/AGENTS.md

Installs project dependencies and starts the full-stack development environment. Uses Yarn 4.13.0 workspaces.

```bash
yarn setup          # Install dependencies
yarn dev            # Start full stack with worktree-isolated ports
```

--------------------------------

### Start Development Stack

Source: https://github.com/hyperdxio/hyperdx/blob/main/CONTRIBUTING.md

Launches the Node.js API, Next.js frontend, OpenTelemetry collector, and ClickHouse server in development mode. Each worktree gets unique ports for simultaneous development.

```bash
yarn dev
```

--------------------------------

### Deploy All-in-one Docker Compose Stack

Source: https://github.com/hyperdxio/hyperdx/blob/main/DEPLOY.md

Clone the repository and run 'docker compose up -d' to start HyperDX, ClickHouse, MongoDB, and an OpenTelemetry collector. This is the simplest way to get started from scratch.

```bash
docker compose up -d
```

--------------------------------

### Setup HyperDX CLI Command

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/hdx-eval/README.md

Initializes HyperDX setup, which includes one-time registration and creation of Sources. Use flags for explicit API URLs or validation.

```bash
dev setup-hyperdx
```

```bash
dev setup-hyperdx --api-url http://...
```

```bash
dev setup-hyperdx --check
```

```bash
dev setup-hyperdx --reset-sources
```

--------------------------------

### Start Full Development Stack

Source: https://github.com/hyperdxio/hyperdx/blob/main/agent_docs/development.md

Starts the complete development environment, automatically assigning unique ports for each worktree. This command is equivalent to 'make dev'.

```bash
yarn dev
```

```bash
make dev
```

--------------------------------

### Start Development Stack with Bash

Source: https://github.com/hyperdxio/hyperdx/blob/main/AGENTS.md

Use this command to start the development stack on systems where /bin/sh is dash. It ensures bash is used for sourcing the dev environment script and then starts the Docker Compose services and the application.

```bash
bash -c 'export PATH="/workspace/node_modules/.bin:$PATH" && source ./scripts/dev-env.sh && yarn build:common-utils && dotenvx run --convention=nextjs -- docker compose -p "$HDX_DEV_PROJECT" -f docker-compose.dev.yml up -d && yarn app:dev'
```

--------------------------------

### Dual-Slot Eval: Setup HyperDX Instances

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/hdx-eval/README.md

Command to run the 'setup-hyperdx' command against each HyperDX instance, targeting specific API URLs for baseline and candidate setups.

```bash
# Setup baseline (slot 98)
yarn workspace @hyperdx/hdx-eval dev setup-hyperdx --api-url http://localhost:30198

# Setup candidate (slot 99)
yarn workspace @hyperdx/hdx-eval dev setup-hyperdx --api-url http://localhost:30199
```

--------------------------------

### Launch Evaluation Viewer

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/hdx-eval/README.md

Start the web-based viewer for comparing evaluation results.

```bash
yarn workspace @hyperdx/hdx-eval viewer    # web UI at http://localhost:5176
```

--------------------------------

### Install Dependencies

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/cli/CONTRIBUTING.md

Install project dependencies from the monorepo root using Yarn.

```bash
yarn install
```

--------------------------------

### Start MCP Inspector Development Server

Source: https://github.com/hyperdxio/hyperdx/blob/main/MCP.md

Run this command to start the MCP Inspector development server. This is useful for interactively testing and debugging the MCP server.

```bash
cd packages/api && yarn dev:mcp
```

--------------------------------

### Start Development Portal Manually

Source: https://github.com/hyperdxio/hyperdx/blob/main/agent_docs/development.md

Manually starts the development portal, which provides a dashboard for all running development stacks. It is automatically started by 'yarn dev'.

```bash
make dev-portal
```

--------------------------------

### Example .env Configuration for Subpath

Source: https://github.com/hyperdxio/hyperdx/blob/main/proxy/README.md

Configure environment variables to serve the application from a subpath like /hyperdx. Ensure `HYPERDX_BASE_PATH` and `NEXT_PUBLIC_HYPERDX_BASE_PATH` match, and `FRONTEND_URL` includes the subpath.

```env
HYPERDX_BASE_PATH=/hyperdx
NEXT_PUBLIC_HYPERDX_BASE_PATH=/hyperdx
FRONTEND_URL=http://localhost:4040/hyperdx
```

--------------------------------

### Page Layout Examples

Source: https://github.com/hyperdxio/hyperdx/blob/main/agent_docs/page_layout.md

Demonstrates correct and incorrect usage of PageLayout and related components for structuring page content, headers, and actions.

```tsx
// ❌ Ad-hoc title in page body
<Group justify="space-between">
  <Text size="xl">Service Map</Text>
  <TimePicker ... />
</Group>

// ✅ Dashboard tool page: breadcrumbs in header, inputs in same sticky block (no `title`)
<PageLayout
  breadcrumbs={<Breadcrumbs>...</Breadcrumbs>}
  leading={<SourceSelect ... />}
  actions={<TimePicker ... />}
  content={<>...</>}
/>

// ❌ Title + breadcrumbs repeating the same page name
<PageLayout title="Kubernetes Dashboard" breadcrumbs={<Breadcrumbs>… Kubernetes</Breadcrumbs>} />

// ❌ Duplicate padding wrapper around the whole page including title
<Box p="sm">
  <Text size="xl">Alerts</Text>
  ...
</Box>

// ✅ Header outside padded content
<PageHeader title="Alerts" />
<Container py="lg">...</Container>
```

--------------------------------

### Quick Start: HDX Eval Commands

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/hdx-eval/README.md

Provides a sequence of commands to set up, seed, run, grade, and report on evaluations using the HDX Eval framework. Ensure HDX_DEV_SLOT is set correctly for your development environment.

```bash
# Set the slot for your session (must match the running dev stack)
export HDX_DEV_SLOT=80

# 1. One-time setup: register eval account + create Sources + write config
yarn workspace @hyperdx/hdx-eval dev setup-hyperdx

# 2. Seed a scenario (use --volume-factor 0.1 for faster iteration)
yarn workspace @hyperdx/hdx-eval dev seed error-root-cause --volume-factor 0.1

# 3. Run the eval (all enabled MCPs, 3 runs each)
#    First run saves an anchorTime to eval.config.json automatically.
yarn workspace @hyperdx/hdx-eval dev run error-root-cause

# 4. Re-run later — reuses saved anchor, skips reseed
yarn workspace @hyperdx/hdx-eval dev run error-root-cause

# 5. Grade + report (auto-runs after step 3 by default)
yarn workspace @hyperdx/hdx-eval dev grade <batch>
yarn workspace @hyperdx/hdx-eval dev report <batch>

# 6. Browse results in the web viewer
yarn workspace @hyperdx/hdx-eval viewer
```

--------------------------------

### Dev-Mode Theme Switching via Console

Source: https://github.com/hyperdxio/hyperdx/blob/main/agent_docs/themes.md

Examples of using the global `window.__HDX_THEME` object in the browser console to switch themes during development.

```javascript
window.__HDX_THEME.set('clickstack')
```

```javascript
window.__HDX_THEME.toggle()
```

```javascript
window.__HDX_THEME.clear()
```

--------------------------------

### Run TUI with Search and Follow Mode

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/cli/CONTRIBUTING.md

Start the interactive TUI with a predefined search query and enable follow mode to continuously stream new results.

```bash
yarn dev tui -q "level:error" -f
```

--------------------------------

### E2E Tests Setup and Execution with Playwright

Source: https://github.com/hyperdxio/hyperdx/blob/main/AGENTS.md

Setup Chromium browser for Playwright E2E tests. Run all E2E tests with 'make e2e'. Use 'make dev-e2e' for hot-reloading specific test files or filtering by name.

```bash
# First-time setup (install Chromium browser):
cd packages/app && yarn playwright install chromium

# Run all E2E tests:
make e2e

# Run a specific test file (dev mode: hot reload):
make dev-e2e FILE=navigation                    # Match files containing "navigation"
make dev-e2e FILE=navigation GREP="help menu"   # Also filter by test name
make dev-e2e GREP="should navigate"             # Filter by test name across all files
make dev-e2e FILE=navigation REPORT=1           # Open HTML report after run

make dev-e2e-clean                               # Remove test artifacts
```

--------------------------------

### Run HyperDX Local Docker Container

Source: https://github.com/hyperdxio/hyperdx/blob/main/LOCAL.md

This command starts the HyperDX Local Docker container, forwarding the necessary ports for the UI and OpenTelemetry endpoints. Ensure you have Docker installed and running.

```bash
docker run -p 8000:8000 -p 4318:4318 -p 4317:4317 -p 8080:8080 -p 8002:8002 docker.hyperdx.io/hyperdx/hyperdx-local
```

--------------------------------

### HTML Structure for Theming

Source: https://github.com/hyperdxio/hyperdx/blob/main/agent_docs/themes.md

Example of the root HTML element with applied theme and color scheme classes for CSS variable resolution.

```html
<html class="theme-clickstack" data-mantine-color-scheme="dark">

```

--------------------------------

### Dual-Slot Eval: Start Dev Stacks

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/hdx-eval/README.md

Instructions to start two separate HyperDX dev stacks using fixed slots for A/B comparison between branches. Each slot provides isolated API, App, ClickHouse, and MCP endpoints.

```bash
# Slot 98: "baseline" — run from your main branch checkout
HDX_DEV_SLOT=98 yarn dev

# Slot 99: "candidate" — run from your feature branch checkout
HDX_DEV_SLOT=99 yarn dev
```

--------------------------------

### Add Source Map Upload to npm Scripts

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/cli/README.md

Integrate the source map upload process into your project's npm scripts for convenience. This example shows how to add an 'upload-sourcemaps' script that uses the CLI. The --path argument is configured to point to the '.next' directory.

```json
{
  "scripts": {
    "upload-sourcemaps": "npx @hyperdx/cli upload-sourcemaps --path=\".next\""
  }
}
```

--------------------------------

### Run All Unit Tests

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/hdx-eval/README.md

Execute all unit tests for the @hyperdx/hdx-eval package in a CI environment. No additional setup like ClickHouse is required.

```bash
yarn workspace @hyperdx/hdx-eval ci:unit   # all unit tests
```

--------------------------------

### Open and Stream Logs

Source: https://github.com/hyperdxio/hyperdx/blob/main/scripts/dev-portal/index.html

Opens a log panel for a specific service and environment, and starts a Server-Sent Events (SSE) stream to display logs in real-time. Handles initial loading messages, stream endings, and errors.

```javascript
function openLogPanel(slot, service, envType) {
  envType = envType || 'dev';
  // Close existing stream
  if (currentEventSource) {
    currentEventSource.close();
    currentEventSource = null;
  }
  currentLogSlot = slot;
  currentLogService = service;
  currentLogEnvType = envType;
  logTitle.textContent = serviceDisplayName(service);
  logSlotLabel.textContent = `${envTypeLabel(envType)} \u00b7 slot ${slot}`;
  logContent.innerHTML = '';
  appendLogLine('Loading logs...');
  logPanel.classList.add('open');
  logStreamBadge.style.display = 'none';
  // Highlight active row
  document
    .querySelectorAll('.services-table tr.active')
    .forEach(el => el.classList.remove('active'));
  const activeRow = document.querySelector(
    `tr[data-slot="${slot}"]\[data-service="${service}"\]\[data-env="${envType}"\]`,
  );
  if (activeRow) activeRow.classList.add('active');
  // Start SSE stream
  const eventSource = new EventSource(
    `/api/logs/${envType}/${slot}/${encodeURIComponent(service)}?stream=1`,
  );
  currentEventSource = eventSource;
  let firstMessage = true;
  eventSource.onmessage = event => {
    if (firstMessage) {
      logContent.innerHTML = '';
      logStreamBadge.style.display = 'inline-flex';
      firstMessage = false;
    }
    appendLogLine(event.data);
  };
  eventSource.addEventListener('close', () => {
    logStreamBadge.style.display = 'none';
    appendLogLine('--- stream ended ---');
  });
  eventSource.onerror = () => {
    logStreamBadge.style.display = 'none';
    if (firstMessage) {
      logContent.innerHTML = '';
      appendLogLine('No logs available for this service.');
    }
    eventSource.close();
  };
}
```

--------------------------------

### Correct Color Selection Example

Source: https://github.com/hyperdxio/hyperdx/blob/main/agent_docs/themes.md

Use CSS variables like `--color-bg-brand` for color selection to ensure correct resolution across brands and color modes.

```tsx
// ✅ resolves correctly for both brands and both color modes
<Box style={{ background: 'var(--color-bg-brand)' }} />
```

--------------------------------

### Full-Stack E2E Test Example

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/app/tests/e2e/README.md

Example of a full-stack E2E test using Playwright. Tests requiring full-stack mode should be tagged with '@full-stack'.

```typescript
import { expect, test } from '../../utils/base-test';
import { SearchPage } from '../page-objects/SearchPage';

test.describe('My Feature', { tag: '@full-stack' }, () => {
  test('should allow authenticated user to save search', async ({ page }) => {
    const ts = Date.now();
    const searchPage = new SearchPage(page);

    await searchPage.goto();
    await searchPage.openSaveSearchModal();
    await searchPage.savedSearchModal.saveSearchAndWaitForNavigation(
      `My Saved Search ${ts}`,
    );

    await expect(searchPage.alertsButton).toBeVisible();
  });
});
```

--------------------------------

### Run Unit Tests for a Package

Source: https://github.com/hyperdxio/hyperdx/blob/main/CONTRIBUTING.md

Navigates to a specific package directory and runs its unit tests. This command is executed within the package's directory.

```bash
yarn dev:unit
```

--------------------------------

### Direct Command Usage (Full-Stack and Local Modes)

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/app/tests/e2e/README.md

Demonstrates direct usage of the `yarn test:e2e` command from the `packages/app` directory, showcasing various modes and flags.

```bash
# Full-stack mode (default, with backend)
yarn test:e2e

# Local mode (frontend only)
yarn test:e2e --local

# Combine with other flags
yarn test:e2e --ui                    # UI mode (full-stack)
yarn test:e2e --ui --local            # UI mode (local)
yarn test:e2e --debug                 # Debug mode (full-stack)
yarn test:e2e --debug --local         # Debug mode (local)
yarn test:e2e --headed                # Visible browser (full-stack)
yarn test:e2e --headed --local        # Visible browser (local)

# Run specific test with any mode
yarn test:e2e tests/e2e/features/search/search.spec.ts
yarn test:e2e tests/e2e/features/dashboard.spec.ts --local
```

--------------------------------

### List Available Sources

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/cli/CONTRIBUTING.md

Display a list of all available data sources that can be queried or streamed.

```bash
yarn dev sources
```

--------------------------------

### Stop Development Stack

Source: https://github.com/hyperdxio/hyperdx/blob/main/CONTRIBUTING.md

Shuts down the development stack started with `yarn dev`.

```bash
yarn dev:down
```

--------------------------------

### List Scenarios and Tables CLI Command

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/hdx-eval/README.md

Lists available scenarios and their associated ClickHouse tables.

```bash
dev list
```

--------------------------------

### Simplified Dockerfile Copy for Local Components

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/otel-collector/README.md

A simplified Dockerfile instruction to copy all necessary files from the otel-collector package.

```dockerfile
COPY packages/otel-collector/ .

```

--------------------------------

### Run Unit Tests in packages/app

Source: https://github.com/hyperdxio/hyperdx/blob/main/AGENTS.md

Use 'yarn ci:unit' to run unit tests in the packages/app directory. Use 'yarn dev:unit' for watch mode.

```bash
cd packages/app
yarn ci:unit           # Run unit tests
yarn dev:unit          # Watch mode for unit tests
```

--------------------------------

### Manage Theme

Source: https://github.com/hyperdxio/hyperdx/blob/main/scripts/dev-portal/index.html

Handles theme preference storage, application, and OS preference detection. Applies theme immediately to prevent flashing.

```javascript
function getPreferredTheme() {
  const stored = localStorage.getItem('hdx-dev-portal-theme');
  if (stored === 'light' || stored === 'dark') return stored;
  return window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
}
function applyTheme(theme) {
  document.documentElement.setAttribute('data-theme', theme);
  const sunIcon = document.getElementById('theme-icon-sun');
  const moonIcon = document.getElementById('theme-icon-moon');
  if (sunIcon && moonIcon) {
    // Sun icon shown in dark mode (click to go light), moon in light mode
    sunIcon.style.display = theme === 'dark' ? '' : 'none';
    moonIcon.style.display = theme === 'light' ? '' : 'none';
  }
}
function toggleTheme() {
  const current = document.documentElement.getAttribute('data-theme') || 'dark';
  const next = current === 'dark' ? 'light' : 'dark';
  localStorage.setItem('hdx-dev-portal-theme', next);
  applyTheme(next);
}
// Apply immediately to avoid flash
applyTheme(getPreferredTheme());
// Listen for OS theme changes (only when no explicit preference saved)
window
  .matchMedia('(prefers-color-scheme: light)')
  .addEventListener('change', () => {
    if (!localStorage.getItem('hdx-dev-portal-theme')) {
      applyTheme(getPreferredTheme());
    }
  });
```

--------------------------------

### Run Integration Tests

Source: https://github.com/hyperdxio/hyperdx/blob/main/AGENTS.md

Runs integration tests for a specified file, spinning up Docker services as needed.

```make
make dev-int FILE=<name>
```

--------------------------------

### Start Dev Stack with Specific Slot

Source: https://github.com/hyperdxio/hyperdx/blob/main/agent_docs/development.md

Overrides the auto-computed worktree slot and uses a specific slot number for the development environment. This is useful for manual control over port assignments.

```bash
HDX_DEV_SLOT=5 make dev
```

--------------------------------

### Run Tests with Options (Full-Stack Mode)

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/app/tests/e2e/README.md

Provides options to run specific tests or use the Playwright UI for interactive debugging. These commands are executed from the repository root.

```bash
./scripts/test-e2e.sh --ui
./scripts/test-e2e.sh --grep "@kubernetes"
./scripts/test-e2e.sh --grep "@smoke"
./scripts/test-e2e.sh --ui --last-failed
```

--------------------------------

### Incorrect Color Selection Example

Source: https://github.com/hyperdxio/hyperdx/blob/main/agent_docs/themes.md

Avoid directly using `themeName` to pick colors, as this bypasses the CSS variable system and can break dark mode and future theme compatibility.

```tsx
// ❌ bypasses the whole CSS var system, breaks dark mode, breaks future themes
const accent = themeName === 'clickstack' ? '#faff69' : '#00c28a';
```

--------------------------------

### Build Integration Test Dependencies

Source: https://github.com/hyperdxio/hyperdx/blob/main/CONTRIBUTING.md

Builds necessary dependencies before running integration tests for the first time.

```bash
make dev-int-build
```

--------------------------------

### Run a Specific OpenTelemetry Collector Smoke Test

Source: https://github.com/hyperdxio/hyperdx/blob/main/smoke-tests/otel-collector/README.md

Execute a single Bats test file, for example, 'hdx-1453-auto-parse-json.bats', to test a specific OpenTelemetry Collector scenario. Navigate to the smoke-tests/otel-collector directory first.

```bash
bats hdx-1453-auto-parse-json.bats
```

--------------------------------

### Navigate to CLI Package

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/cli/CONTRIBUTING.md

Change directory to the CLI package within the monorepo.

```bash
cd packages/cli
```

--------------------------------

### Accessing Theme and Brand Info in React

Source: https://github.com/hyperdxio/hyperdx/blob/main/agent_docs/themes.md

Use these hooks to get the current theme object, theme name, and brand display name. Useful for conditional UI rendering and brand-specific copy.

```tsx
import { useAppTheme, useThemeName, useBrandDisplayName } from '@/theme/ThemeProvider';

function Header() {
  const { theme } = useAppTheme();          // full ThemeConfig
  const themeName = useThemeName();          // 'hyperdx' | 'clickstack'
  const brand = useBrandDisplayName();       // 'HyperDX' | 'ClickStack' — use in UI copy
  // …
}
```

--------------------------------

### Render Stacks Dashboard

Source: https://github.com/hyperdxio/hyperdx/blob/main/scripts/dev-portal/index.html

Renders the main dashboard view for running stacks. If no stacks are running, it displays a helpful message with commands to start environments. Otherwise, it groups stacks by worktree and renders a card for each.

```javascript
function renderStacks(stacks) {
  if (stacks.length === 0) {
    return ` <div class="empty-state">
 <h2>No stacks running</h2>
 <p>Start an environment from a worktree:</p>
 <br>
 <code>make dev</code> &nbsp; <code>make dev-e2e</code> &nbsp; <code>make dev-int</code>
 </div> `;
  }
  // Group stacks by worktree name so all envs for the same
  // worktree appear in a single card.
  const groups = new Map();
  for (const stack of stacks) {
    const key = stack.worktree || 'unknown';
    if (!groups.has(key)) groups.set(key, []);
    groups.get(key).push(stack);
  }
  return `<div class="stacks">
${
    [...groups.values()].map(renderWorktreeCard).join('')
  }</div>`;
}
```

--------------------------------

### Run Unit and Integration Tests in packages/common-utils

Source: https://github.com/hyperdxio/hyperdx/blob/main/AGENTS.md

Commands for running unit and integration tests in packages/common-utils. Includes commands for both standard execution and watch mode.

```bash
cd packages/common-utils
yarn ci:unit           # Run unit tests
yarn dev:unit          # Watch mode for unit tests
yarn ci:int            # Run integration tests
yarn dev:int           # Watch mode for integration tests
```

--------------------------------

### Build and Verify OTel Collector Image

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/otel-collector/README.md

Builds the OpenTelemetry Collector development image, checks its version, and removes the test image.

```bash
docker build -f docker/otel-collector/Dockerfile --target dev -t hdx-otel-test .
docker run --rm --entrypoint /otelcontribcol hdx-otel-test --version
docker rmi hdx-otel-test
```

--------------------------------

### Run HyperDX All-in-One Docker Image

Source: https://github.com/hyperdxio/hyperdx/blob/main/README.md

This command deploys HyperDX along with ClickHouse, OpenTelemetry Collector, and MongoDB. Access the UI at http://localhost:8080 after deployment. Ensure ports 8080, 8000, and 4318 are open if behind a firewall.

```bash
docker run -p 8080:8080 -p 4317:4317 -p 4318:4318 docker.hyperdx.io/hyperdx/hyperdx-all-in-one
```

--------------------------------

### Stdio MCP Configuration (ClickHouse)

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/hdx-eval/README.md

Configuration for a stdio-based MCP using raw ClickHouse. Specifies the command, arguments, environment variables, and tool pattern.

```json
{
  "type": "stdio",
  "command": "uv",
  "args": ["run", "--with", "mcp-clickhouse==0.3.0", "--python", "3.10", "mcp-clickhouse"],
  "env": {
    "CLICKHOUSE_HOST": "localhost",
    "CLICKHOUSE_PORT": "30598",
    "CLICKHOUSE_USER": "default",
    "CLICKHOUSE_PASSWORD": ""
  },
  "toolPattern": "mcp__clickhouse__*",
  "label": "ClickHouse MCP",
  "brandTerms": ["ClickHouse MCP", "clickhouse"]
}
```

--------------------------------

### Bundle CLI with tsup

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/cli/AGENTS.md

Bundle the CLI application using tsup for production deployment.

```bash
yarn build
```

--------------------------------

### Run Integration Tests in packages/api

Source: https://github.com/hyperdxio/hyperdx/blob/main/AGENTS.md

Build dependencies with 'make dev-int-build' before running integration tests. Use 'make dev-int FILE=<TEST_FILE_NAME>' to run tests with Docker services.

```bash
make dev-int-build                  # Build dependencies (run once before tests)
make dev-int FILE=<TEST_FILE_NAME>  # Spins up Docker services and runs tests.
                                    # Ctrl-C to stop and wait for all services to tear down.
```

--------------------------------

### Add Host Entry for Local Domain

Source: https://github.com/hyperdxio/hyperdx/blob/main/docker/nginx/README.md

Update the /etc/hosts file to map a local domain to the loopback address for local development and testing.

```bash
127.0.0.1 mydomain.local
```

--------------------------------

### Run Specific Integration Test

Source: https://github.com/hyperdxio/hyperdx/blob/main/CONTRIBUTING.md

Executes a specific integration test file. Ensure dependencies are built first.

```bash
make dev-int FILE=checkAlerts
```

--------------------------------

### Run All E2E Tests

Source: https://github.com/hyperdxio/hyperdx/blob/main/CONTRIBUTING.md

Executes all end-to-end tests against a full local stack. Docker must be running.

```bash
make e2e
```

--------------------------------

### Compile Standalone Binary

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/cli/AGENTS.md

Compile the CLI application into a standalone binary for the current platform.

```bash
yarn compile
```

--------------------------------

### Default Log Source Configuration

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/api/docs/auto_provision/AUTO_PROVISION.md

Configure default log sources by providing a JSON array to the `DEFAULT_SOURCES` environment variable. Each source requires a name, kind, connection, and 'from' object specifying database and table names, along with various expression fields.

```json
[
  {
    "name": "HyperDX Logs",
    "kind": "log",
    "connection": "Local ClickHouse",
    "from": {
      "databaseName": "default",
      "tableName": "logs"
    },
    "timestampValueExpression": "timestamp",
    "displayedTimestampValueExpression": "timestamp",
    "bodyExpression": "body",
    "severityTextExpression": "severity_text",
    "serviceNameExpression": "service_name",
    "resourceAttributesExpression": "resource",
    "traceIdExpression": "trace_id",
    "spanIdExpression": "span_id"
  }
]
```

--------------------------------

### Default Connection Configuration

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/api/docs/auto_provision/AUTO_PROVISION.md

Provide a JSON array of connection objects to the `DEFAULT_CONNECTIONS` environment variable. Each object requires a name, host, and username, with an optional password.

```json
[
  {
    "name": "Local ClickHouse",
    "host": "clickhouse:8123",
    "username": "default",
    "password": ""
  }
]
```

--------------------------------

### Run Unit Tests

Source: https://github.com/hyperdxio/hyperdx/blob/main/AGENTS.md

Executes all unit tests across all packages in the project.

```make
make ci-unit
```

--------------------------------

### Run Evals with Various Options

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/hdx-eval/README.md

Execute evaluation scenarios with different configurations for MCPs, runs, models, and other parameters.

```bash
dev run <scenario>                          # all enabled MCPs, 3 runs each
dev run <scenario> --mcp hyperdx            # single MCP
dev run <scenario> --mcp hyperdx-main,hyperdx-feature  # compare two
dev run <scenario> --mcp all                # all enabled MCPs (default)
dev run <scenario> --baseline hyperdx-main  # set baseline for delta reports
dev run <scenario> --runs 5                 # 5 runs per cell
dev run <scenario> --model claude-opus-4-6
dev run <scenario> --max-turns 20           # default: 15
dev run <scenario> --concurrency 4          # parallel cells
dev run <scenario> --prompt-variant hypothesis  # hypothesis-first variant
dev run <scenario> --reseed                 # re-seed data before running
dev run <scenario> --anchor-time 2026-05-08T15:00:00Z  # override + save anchor
dev run <scenario> --live                   # wall-clock now, no anchor, forces reseed
dev run <scenario> --no-grade               # skip auto-grading
dev run <scenario> --no-judge               # programmatic checks only (faster)
```

--------------------------------

### Run TUI Skipping Source Picker

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/cli/CONTRIBUTING.md

Launch the interactive TUI and skip the source selection step by explicitly providing the desired source name.

```bash
yarn dev tui --source "Logs"
```

--------------------------------

### Seed Scenario with Full Volume

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/hdx-eval/README.md

Seeds a scenario with default settings and full background volume. Realistic difficulty for finding anomalies.

```bash
yarn workspace @hyperdx/hdx-eval dev seed error-root-cause
```

--------------------------------

### Run Specific Unit Tests in packages/common-utils

Source: https://github.com/hyperdxio/hyperdx/blob/main/AGENTS.md

Execute specific unit tests by providing a file path or a test name pattern.

```bash
yarn ci:unit <path/to/test.ts>                           # Run specific test file
yarn ci:unit --testNamePattern="test name pattern"       # Run tests matching pattern
```

--------------------------------

### GitHub Action Workflow Commands

Source: https://github.com/hyperdxio/hyperdx/blob/main/AGENTS.md

Commands to run for linting, type checking, and unit tests within a GitHub Action workflow before opening a PR.

```bash
make ci-lint        # lint + TypeScript type check
make ci-unit        # unit tests
```

--------------------------------

### Run HyperDX with Existing ClickHouse

Source: https://github.com/hyperdxio/hyperdx/blob/main/DEPLOY.md

Deploy HyperDX as a Docker container and connect it to your existing MongoDB instance. Ensure MONGO_URI is set. Visit http://localhost:8080 to configure ClickHouse connection.

```bash
docker run -e MONGO_URI=mongodb://YOUR_MONGODB_URI -p 8080:8080 docker.hyperdx.io/hyperdx/hyperdx:2-beta
```

--------------------------------

### Manual Linting Across All Packages

Source: https://github.com/hyperdxio/hyperdx/blob/main/agent_docs/development.md

Run linting checks across all packages in the project.

```bash
yarn run lint
```

--------------------------------

### Run Tests in Full-Stack Mode

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/app/tests/e2e/README.md

Default behavior for running end-to-end tests, including MongoDB, API Server, App Server, and local Docker ClickHouse with seeded E2E test data.

```bash
# Default: full-stack mode
make e2e
./scripts/test-e2e.sh --grep "@kubernetes"   # from repo root, for specific tags
```

--------------------------------

### Run API Integration Tests

Source: https://github.com/hyperdxio/hyperdx/blob/main/agent_docs/development.md

Executes API integration tests. This command spins up Docker services, runs the specified tests, and then tears down the services. The FILE environment variable specifies which test file to run.

```bash
make dev-int FILE=<TEST_FILE_NAME>
```

--------------------------------

### Lint and Type Check Across All Packages

Source: https://github.com/hyperdxio/hyperdx/blob/main/AGENTS.md

Run linting and TypeScript checks across all project packages using 'make ci-lint'. Run unit tests across all packages with 'make ci-unit'.

```bash
make ci-lint        # Lint + TypeScript check across all packages
make ci-unit        # Unit tests across all packages
```

--------------------------------

### Configure MCP Server for OpenCode

Source: https://github.com/hyperdxio/hyperdx/blob/main/MCP.md

Add this JSON configuration to your OpenCode config file to enable the ClickStack MCP server. Ensure you replace the placeholders with your specific details.

```json
"mcp": {
  "clickstack": {
    "enabled": true,
    "type": "remote",
    "url": "<your-hyperdx-url>/api/mcp",
    "headers": {
      "Authorization": "Bearer <your-personal-access-key>"
    }
  }
}
```

--------------------------------

### Run Specific Tests (Full-Stack Mode)

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/app/tests/e2e/README.md

Executes specific end-to-end tests tagged with `@kubernetes` in full-stack mode. This is done from the repository root.

```bash
./scripts/test-e2e.sh --grep "@kubernetes"
```

--------------------------------

### Dashboard Provisioning JSON Format

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/api/docs/auto_provision/AUTO_PROVISION.md

Define dashboard configurations in JSON format for file-based provisioning. Each file should include a name and a tiles array, with individual tiles having unique IDs and configurations.

```json
{
  "name": "My Dashboard",
  "tiles": [
    {
      "id": "tile-1",
      "x": 0,
      "y": 0,
      "w": 6,
      "h": 4,
      "config": {
        "name": "Request Count",
        "source": "Metrics",
        "displayType": "line",
        "select": [{ "aggFn": "count" }]
      }
    }
  ],
  "tags": ["provisioned"]
}
```

--------------------------------

### Run CI Lint Check

Source: https://github.com/hyperdxio/hyperdx/blob/main/AGENTS.md

Executes linting and TypeScript type checking for the project.

```make
make ci-lint
```

--------------------------------

### Run E2E Tests and Open HTML Report

Source: https://github.com/hyperdxio/hyperdx/blob/main/agent_docs/development.md

Execute E2E tests for a specific file and automatically open the HTML report upon completion.

```bash
make dev-e2e FILE=navigation REPORT=1
```

--------------------------------

### Run Tests in Local Mode

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/app/tests/e2e/README.md

Opt-in to local mode for faster execution, skipping MongoDB and API services. This mode uses local Docker ClickHouse with seeded test data and is suitable for frontend-only features.

```bash
# Opt-in to local mode for speed (from repo root)
./scripts/test-e2e.sh --local
./scripts/test-e2e.sh --local --grep "@search"
```

--------------------------------

### Run CLI in Dev Mode

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/cli/AGENTS.md

Execute the CLI in development mode for immediate feedback without a compile step. Ensure you are in the 'packages/cli' directory and have the HyperDX endpoint configured.

```bash
cd packages/cli
yarn dev tui -s http://localhost:8000
```

--------------------------------

### Run HyperDX in Local Development Mode

Source: https://github.com/hyperdxio/hyperdx/blob/main/DEPLOY.md

Spin up a local development instance of HyperDX, including an OpenTelemetry collector, ClickHouse, and MongoDB. This mode is suitable for local debugging and does not include authentication or persistence.

```bash
docker run -p 8080:8080 docker.hyperdx.io/hyperdx/hyperdx-local:2-beta
```

--------------------------------

### Upload Source Maps with CLI

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/cli/README.md

Use this command in your build pipeline to upload JavaScript source maps for stack trace de-obfuscation. Ensure the HYPERDX_API_ACCESS_KEY and RELEASE_ID environment variables are set, or provide them as flags. The --path flag specifies the directory containing the source maps.

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

--------------------------------

### Configure MCP Server for Cursor

Source: https://github.com/hyperdxio/hyperdx/blob/main/MCP.md

Add this JSON configuration to your project's .cursor/mcp.json file or your global Cursor settings to connect to the ClickStack MCP server.

```json
{
  "mcpServers": {
    "clickstack": {
      "url": "<your-hyperdx-url>/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-personal-access-key>"
      }
    }
  }
}
```

--------------------------------

### Run Local Mode Tests (Frontend Only)

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/app/tests/e2e/README.md

Executes end-to-end tests in local mode, skipping MongoDB and API services to focus solely on the frontend. This is useful for faster development iterations.

```bash
# From repo root - run local tests (no MongoDB, frontend only)
./scripts/test-e2e.sh --local
./scripts/test-e2e.sh --local --ui
./scripts/test-e2e.sh --local --grep "@search"

# From packages/app - run local tests (frontend only)
cd packages/app
yarn test:e2e --local
```

--------------------------------

### Show Trace Viewer for Failed Tests

Source: https://github.com/hyperdxio/hyperdx/blob/main/packages/app/tests/e2e/README.md

Utilize the trace viewer for in-depth debugging of failed tests by providing the path to the trace zip file.

```bash
yarn playwright show-trace test-results/[test-name]/trace.zip
```