@kopai/cli

CLI for querying OpenTelemetry data from Kopai - traces, logs, and metrics.

Works with @kopai/app or any compatible backend.

Usage

npx @kopai/cli traces search --service my-api

Global Install (optional)

npm install -g @kopai/cli
kopai traces search --service my-api

Quick Start

# Search for error traces
kopai traces search --status-code ERROR --limit 10

# Get all spans for a trace
kopai traces get <traceId>

# Search logs by service
kopai logs search --service my-api --limit 20

# Discover available metrics
kopai metrics discover

By default connects to http://localhost:8000.

Configuration

Global Options

| Option | Description | | ------------------------ | ---------------- | | --url <url> | API base URL | | --token <token> | Auth token | | --config <path> / -c | Config file path | | --timeout <ms> | Request timeout |

Config File

Create .kopairc in project root or home directory:

{
  "url": "https://your-kopai-server.com",
  "token": "your-token"
}

Priority: CLI flags → local .kopairc → ~/.kopairc → defaults

Commands

traces

traces get <traceId>

Get all spans for a trace.

kopai traces get abc123def456

traces search

Search traces with filters.

kopai traces search --service my-api --status-code ERROR
kopai traces search --span-name "POST /users" --duration-min 1000000000
kopai traces search --span-attr "http.method=GET" --resource-attr "k8s.pod.name=web-1"

Filters:

• --trace-id, --span-id, --parent-span-id
• -s, --service - service name
• --span-name - span name
• --span-kind - CLIENT, SERVER, PRODUCER, CONSUMER, INTERNAL
• --status-code - OK, ERROR, UNSET
• --scope - instrumentation scope
• --timestamp-min, --timestamp-max - nanoseconds
• --duration-min, --duration-max - nanoseconds
• --span-attr <key=value> - repeatable
• --resource-attr <key=value> - repeatable
• --sort - ASC or DESC

Fields: SpanId, TraceId, Timestamp, Duration, ParentSpanId, ServiceName, SpanName, SpanKind, StatusCode, StatusMessage, SpanAttributes, ResourceAttributes, ScopeName, ScopeVersion, TraceState, Events, Links

logs

logs search

Search logs with filters.

kopai logs search --service my-api --severity-text ERROR
kopai logs search --trace-id abc123 --body "connection failed"
kopai logs search --log-attr "user.id=123"

Filters:

• --trace-id, --span-id - correlate with traces
• -s, --service - service name
• --scope - scope name
• --severity-text - DEBUG, INFO, WARN, ERROR, FATAL
• --severity-min, --severity-max - 0-24
• -b, --body - body content substring
• --timestamp-min, --timestamp-max - nanoseconds
• --log-attr <key=value> - repeatable
• --resource-attr <key=value> - repeatable
• --scope-attr <key=value> - repeatable
• --sort - ASC or DESC

Fields: Timestamp, TraceId, SpanId, ServiceName, SeverityText, SeverityNumber, Body, LogAttributes, ResourceAttributes, ScopeName, ScopeVersion, ScopeAttributes, TraceFlags

metrics

metrics search --type <type>

Search metrics by type.

kopai metrics search --type Gauge --name cpu_usage
kopai metrics search --type Histogram --service my-api
kopai metrics search --type Sum --attr "host=server1"

# Aggregate: total bytes ingested grouped by signal
kopai metrics search --type Sum --name kopai.ingestion.bytes --aggregate sum --group-by signal

Types: Gauge, Sum, Histogram, ExponentialHistogram, Summary

Filters:

• -n, --name - metric name
• -s, --service - service name
• --scope - scope name
• --time-min, --time-max - nanoseconds
• -a, --attr <key=value> - repeatable
• --resource-attr <key=value> - repeatable
• --scope-attr <key=value> - repeatable
• --sort - ASC or DESC
• --aggregate <fn> - aggregation function (sum, avg, min, max, count). Gauge/Sum only
• --group-by <attr> - group by attribute key (repeatable, requires --aggregate)

Fields: TimeUnix, StartTimeUnix, MetricType, MetricName, MetricDescription, MetricUnit, ServiceName, Value, Count, Sum, Min, Max, Attributes, ResourceAttributes, ScopeName, ScopeAttributes, Exemplars, BucketCounts, ExplicitBounds

dashboards

dashboards schema

Print the UI tree component schema (for AI agents).

kopai dashboards schema

dashboards create

Create a dashboard. Reads uiTree JSON from stdin.

echo '{"uiTree":{...},"metadata":{}}' | kopai dashboards create --name "My Dashboard" --tree-version "0.5.0" --json

Required flags:

• --name <name> - Dashboard display name
• --tree-version <semver> - UI tree version (e.g. "0.5.0")

Stdin JSON should contain uiTree (required) and optionally metadata. If the JSON has no uiTree key, the entire object is treated as the uiTree.

metrics discover

List available metrics.

kopai metrics discover
kopai metrics discover --json

Fields: name, type, unit, description, attributes, resourceAttributes

Output Options

| Option | Description | | ---------------------- | ---------------------- | | -j, --json | JSON output | | -t, --table | Table output | | -f, --fields <f1,f2> | Select specific fields | | -l, --limit <n> | Max results |

Auto-detection: TTY outputs table, piped output defaults to JSON.

# Select specific fields
kopai traces search --fields "SpanId,ServiceName,Duration"

# Pipe JSON to jq
kopai logs search --json --service my-api | jq '.[] | .Body'

Exit Codes

| Code | Meaning | | ---- | ----------------- | | 0 | Success | | 1 | API/runtime error | | 2 | Invalid arguments | | 3 | Config error |

Examples

# Find slow traces (>1s duration)
kopai traces search --duration-min 1000000000 --json

# Get logs correlated with a trace
kopai traces get abc123 --fields TraceId
kopai logs search --trace-id abc123

# Export error logs as JSON
kopai logs search --severity-text ERROR --json > errors.json

# Monitor specific service
kopai traces search --service payment-api --status-code ERROR --limit 50