openobserve-cli

Capabilities

Read your observability data, the agent way

Discover streams and search logs, metrics and traces — with output a coding agent can act on.

Logs: SQL & live tail

Run full SQL over any stream — WHERE, GROUP BY, aggregates — built from --stream/--where or your own --sql; or search tail to follow it live.

Metrics & traces

Query metrics with PromQL — metrics query / query-range — and reassemble a trace into a span waterfall with trace get.

Map before terrain

search histogram shows volume per time bucket, and trace search surfaces recent traces, so an agent sees the shape before pulling raw rows.

Stream discovery

List streams and inspect a stream's schema and full-text-search keys — so your SQL only ever references real names.

Human time ranges

Pass --since 1h or --from/--to as RFC3339, a date, an epoch, or now-30m — the CLI converts to the microseconds the API needs.

Agent-first output

JSON by default, with structured errors — categories, exit codes and recovery next_steps a coding agent can branch on.

Multiple servers

kubectl-style named contexts in one config file. Switch the current server, or override per command with --use-context.

Secure credentials

Passwords and tokens live in the OS keychain, with a per-user DPAPI fallback on Windows and a 0600 fallback on macOS/Linux — never in the config file. Env vars for headless use.

SSO & service accounts

Works behind dex / Authentik / Okta SSO via a Service Account token, and gives RBAC-aware guidance when a 403 means a missing role.

Install

Up and running in a minute

Install with npm, then finish setup in two steps — deploy the Skill, then turn on shell completion.

install

# recommended — fetches the prebuilt binary for your platform
npm install -g @angelmsger/openobserve-cli

Other methods — go install, a source build, or a prebuilt binary from the Releases page — are in the README.

Then finish setup:

1 · Companion Skill

An openobserve Skill is embedded in the binary. It detects your coding agent — Claude Code, Codex — and installs for each:

$ openobserve-cli skill install

2 · Shell completion

Completes subcommands and flag values. Load it once:

$ source <(openobserve-cli completion bash)

Quick start

Configure once, then read the data

Set up a server, discover streams, then search — map first, then rows.

a typical session

# interactive setup, then verify connectivity
$ openobserve-cli config init --pretty
$ openobserve-cli doctor

# discover streams, then inspect one's columns
$ openobserve-cli stream list
$ openobserve-cli stream schema default

# see volume over time, then pull the rows behind a spike
$ openobserve-cli search histogram --stream default --since 6h --interval 5m
$ openobserve-cli search run --stream default \
    --where "level = 'ERROR'" --since 1h --limit 20

# metrics with PromQL, and a trace's span waterfall
$ openobserve-cli metrics query-range --query 'sum(rate(http_requests_total[5m]))' --since 1h --step 1m
$ openobserve-cli trace get <trace_id> --stream default --since 1h