openobservecli

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 (Claude Code, Codex, Grok Build, Pi) through the CLI.

Scope (v0.2): read-only — organizations, streams (discovery + schema), SQL search / histogram / tail, PromQL metrics, and trace search / get. Dashboards, alerts, functions/pipelines, users and ingestion are planned; the write-safety gates (--dry-run, --yes, session read-only) are already wired for them.

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

2. Deploy the companion Skill

The openobserve Skill is embedded in the binary; it teaches your coding agent (Claude Code, Codex, Cursor, Agents (shared), Gemini CLI, GitHub Copilot, OpenCode, Continue, Windsurf, Grok Build, Pi, Kilo Code, and Roo Code) how to drive the CLI. skill install probes for installed agents and installs into each one found:

openobserve-cli skill install            # auto-detect; install for each agent found
openobserve-cli skill install --agent codex
openobserve-cli skill uninstall          # remove it again

Re-run it after upgrading the CLI to keep the Skill version-matched.

3. Enable shell completion (optional)

source <(openobserve-cli completion bash)                         # bash, current shell
openobserve-cli completion zsh > "${fpath[1]}/_openobserve-cli"    # zsh, persistent

fish and PowerShell are supported too — see openobserve-cli completion --help.

Quick start

openobserve-cli config init --pretty  # interactive TUI setup (recommended for humans)
openobserve-cli doctor                # verify configuration and connectivity

openobserve-cli org list              # discover organizations
openobserve-cli stream list           # discover streams (the map)
openobserve-cli stream schema default # queryable columns + search settings

# logs: volume over time, then 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: error rate over the last hour, one point per minute (PromQL)
openobserve-cli metrics query-range \
  --query 'sum(rate(http_requests_total{status=~"5.."}[5m]))' --since 1h --step 1m

# traces: find a recent trace, then open its span waterfall
openobserve-cli trace search --stream default --since 1h --limit 20
openobserve-cli trace get <trace_id> --stream default --since 1h

Configuration

Settings resolve in precedence order (highest first): CLI flags → environment variables (OPENOBSERVE_*) → .env → ~/.angelmsger/openobserve/config.yaml → defaults. Secrets are stored in the OS keychain. If Windows Credential Manager is unavailable, the fallback is encrypted with per-user DPAPI; macOS/Linux retain the 0600 fallback. Secrets are never written to the config file.

For headless / CI / agent use, configure entirely from the environment:

export OPENOBSERVE_URL=http://localhost:5080      # or https://api.openobserve.ai
export OPENOBSERVE_ORG=default
export OPENOBSERVE_EMAIL=root@example.com
export OPENOBSERVE_PASSWORD='Complexpass#123'
# …or a pre-generated token instead of email+password:
export OPENOBSERVE_TOKEN='<base64-or-Basic/Bearer value>'

SSO / OAuth (dex, Authentik, Okta…)

When OpenObserve logs users in through an external identity provider, those users have no local password and cannot authenticate the CLI directly. Create a Service Account (IAM → Service Accounts), assign it a role, then use its email + token as the credentials above (the token goes in the password position). See the SSO / OAuth section of the getting-started reference for the full walkthrough.

Browser sign-in

Instances behind SSO cannot use a password or a generated token. Sign in through a real browser instead:

openobserve-cli auth login --browser

A browser window opens on your instance's login page; once you are signed in the CLI captures the session, verifies it with an authenticated request, and stores it in the OS keychain. The captured session is the same one the o3 desktop app uses, so signing in through either leaves the other authenticated.

Requires a Chromium-family browser (Chrome, Chromium, Edge or Brave) and a graphical session. Set OPENOBSERVE_BROWSER to choose a specific one. The browser profile is remembered under ~/.angelmsger/openobserve/browser-profile so you are not sent through SSO on every login; --fresh-profile opts out, and auth logout removes it.

Commands

In the default JSON output, list commands return a {items, next, has_more} envelope; --format ndjson instead streams the items themselves, one JSON object per line (ideal for piping search run hits into jq). --fields a,b.c projects output down to specific dot-paths.

Time ranges accept --since 15m|1h|24h|7d, or --from/--to as RFC3339, a date, an epoch (seconds/millis/micros), or now-30m; the CLI converts to the microsecond timestamps the search API requires.

Multiple servers (contexts)

A single config file can hold several OpenObserve servers as named contexts. Most users need only one and never see the concept. When a config already exists, re-running config init lists it and asks whether to edit a context, add a new one, or replace everything; pass config init --context prod to skip that prompt and target a context directly. Then:

openobserve-cli config contexts                 # list contexts, current marked
openobserve-cli config use-context prod         # switch the current context
openobserve-cli --use-context prod stream list  # override for one command

OPENOBSERVE_CONTEXT overrides the current context via the environment.

Errors and exit codes

Failures are JSON on stderr (stdout stays a clean data channel) and map to stable exit codes: 0 success, 2 usage, 3 config, 4 auth, 5 permission, 6 not found, 7 rate limit, 8 network, 9 server, 10 parse, 11 conflict. Each error carries next_steps naming the command to run next, and retryable to guide back-off.

Use as a Go library

The HTTP client that powers the CLI is published as a standalone Go package, so a GUI or other tool can query OpenObserve directly — same normalized models and structured errors, without shelling out to the binary.

import (
	"context"
	"encoding/base64"
	"net/http"
	"os"

	api "github.com/angelmsger/openobserve-cli/pkg/apiclient"
	cerr "github.com/angelmsger/openobserve-cli/pkg/errors"
	"github.com/angelmsger/openobserve-cli/pkg/transport"
)

// Authentication is a transport.Decorator you supply — it sets the
// Authorization header on every request. OpenObserve uses HTTP Basic
// (email + password); a pre-generated token works too.
func basic(email, password string) transport.Decorator {
	header := "Basic " + base64.StdEncoding.EncodeToString([]byte(email+":"+password))
	return func(r *http.Request) { r.Header.Set("Authorization", header) }
}

ctx := context.Background()
client, err := api.Build(api.BuildParams{
	BaseURL:       "https://o2.example.com:5080",
	Org:           "default",
	AuthDecorator: basic(os.Getenv("OPENOBSERVE_EMAIL"), os.Getenv("OPENOBSERVE_PASSWORD")),
})
if err != nil { /* see error handling below */ }

streams, err := client.ListStreams(ctx, "default", "logs", true) // include schema

The example hand-rolls the decorator to keep dependencies minimal, but two more packages save you the work when you want the CLI's own behavior:

• pkg/auth — the Credential model. It supports basic and token Authorization headers plus browser-captured session envelopes (cookies with an optional Authorization fallback), validates itself, and exposes Credential.Decorator() to drop straight into BuildParams.AuthDecorator.
• pkg/config — the on-disk config-file model (named contexts + current_context + shared defaults, with file IO). Import it to read or write the same config.yaml the CLI uses, so a GUI and the CLI share one config. Secrets are never stored there; passwords, tokens, and captured sessions live in the OS keychain.

Errors are *errors.CLIError with a stable Category and Code, so callers branch on failure kinds instead of parsing strings:

if ce := cerr.AsCLIError(err); ce != nil {
    // ce.Category, ce.Code, ce.Hint, ce.NextSteps, ce.HTTPStatus, ce.Retryable
}

These pkg/... packages primarily back this CLI and its companion Skill; their exported surface is treated as a stable contract. Read the package doc comment (go doc ./pkg/apiclient) before changing it.

Development

make build      # compile to ./bin/openobserve-cli
make test       # unit + httptest integration tests
make e2e        # build + run against an in-repo mock OpenObserve server
make lint       # gofmt + go vet
make docs       # regenerate the CLI reference under docs/cli/

CONTRIBUTING.md covers the conventions and commands; docs/technical-design.md the architecture, and docs/releasing.md the release process. The docs/cli/ reference is generated from the cobra command tree by cmd/gen-docs, so it always matches --help — run make docs after changing a command or flag, and commit the result (CI fails if it drifts). See CHANGELOG.md for the version history.

Related

Part of a family of agent-facing CLIs — one skeleton, one set of conventions, all built for coding agents. Browse the full set at github.com/AngelMsger:

• confluence-cli — Confluence as a knowledge base
• bitbucket-cli — Bitbucket pull requests & code review
• openobserve-cli — OpenObserve logs, metrics & traces (this project)
• jenkins-cli — inspect Jenkins jobs & builds
• jira-cli — Jira issues & workflow transitions

License

Released under the MIT License.