openobserve-cli

Query OpenObserve from your terminal — built for coding agents.

openobserve-cli lets coding agents (Claude Code and others) — and humans — explore an OpenObserve (O2) backend from the command line across all three pillars: discover streams and schema, run SQL searches, histograms and a live tail -f over logs, query metrics with PromQL (instant and range), and reassemble a distributed trace into a span waterfall. It works with both self-hosted OpenObserve and OpenObserve Cloud, returns agent-friendly JSON with structured errors, and ships a companion Skill that teaches an agent how to use it.

📖 Documentation site: https://angelmsger.github.io/openobserve-cli/

$ openobserve-cli search run --stream default --where "level = 'ERROR'" --since 1h --limit 3
{
  "sql": "SELECT * FROM \"default\" WHERE level = 'ERROR' ORDER BY _timestamp DESC",
  "total": 1284, "returned": 3, "took_ms": 18, "scan_size_mb": 4.2,
  "hits": [ { "_timestamp": 1718528391000000, "level": "ERROR", "log": "…" } ]
}

Features

• All three pillars, each with the right tool — logs via full SQL (search run/histogram/tail), metrics via PromQL (metrics query / query-range), traces via a dedicated span model (trace search lists recent traces; trace get rebuilds one into a parent/child waterfall).
• 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 or a full span tree.
• Built for large and live data — search tail follows a stream as ndjson like tail -f; --sql @file / @- reads long queries from a file or stdin; search run --all pages through every matching row (bounded by --max).
• The CLI owns the footguns — human time ranges (--since 1h, --from/--to, RFC3339, epochs, now-30m) are converted to the microsecond timestamps the API needs; stream and column names come from discovery commands, never guesses.
• Agent-friendly output — JSON by default, a {items, next, has_more} list envelope, --format json|table|ndjson, and --fields projection to spend minimal context.
• Errors as navigation — every failure is structured (category/code/hint/next_steps/retryable) and mapped to a stable exit code, so a script or agent can branch and self-recover.
• No dead ends — any identifier a command needs is discoverable from another: a stream from stream list, a column from stream schema, an org from org list.
• Flexible configuration — CLI flags, environment variables, a .env file, a YAML config file, or an interactive wizard; multiple named server contexts; secrets stored in the OS keychain.
• Companion Skill — an openobserve Skill, embedded in the binary, that guides coding agents through the CLI.

Scope (v0.18): telemetry queries remain read-only. Alert and Dashboard management supports discovery, JSON backup/restore, create/update/delete and alert enable/disable. Every write supports --dry-run and honors session read-only mode; deletion requires --yes. Functions/pipelines, users and ingestion remain planned.

SQL search run, search histogram and search tail default to --type logs. For raw metric or trace records, pass the discovered --type metrics or --type traces. Use PromQL for metric calculations and trace get for span trees; trace get selects the traces namespace automatically.

Manage alerts and dashboards

openobserve-cli alert list
openobserve-cli dashboard list --title traffic
openobserve-cli dashboard get <id> --folder <folder-id> > dashboard.json
# Edit dashboard.json while retaining its hash, then preview and apply:
openobserve-cli dashboard update <id> --folder <folder-id> --file dashboard.json --dry-run
openobserve-cli dashboard update <id> --folder <folder-id> --file dashboard.json

Use the IDs and folders returned by the lists. A stale Dashboard backup is rejected with a conflict; fetch the current definition and re-apply your edits. Writes are allowed by default. Set OPENOBSERVE_CLI_READ_ONLY=1 to block them, then use --allow-writes only for an intended mutation. Alert management needs OpenObserve's ID-based v2 API. See the Alert guide, Dashboard guide and read-only mode.

Installation

1. Install the CLI — npm (recommended)

npm install -g @angelmsger/openobserve-cli

npm downloads the prebuilt binary for your platform, verifies its SHA-256 checksum, and keeps upgrades one npm update -g @angelmsger/openobserve-cli away.

go install github.com/angelmsger/openobserve-cli/cmd/openobserve-cli@latest   # go 1.24+
make install                                                                  # from a source checkout

Or download a prebuilt binary from the Releases page. The full installation guide covers every method, shell completion and the companion Skill.

This is the beginning of the README. Read the rest at the original. Read the full README ↗