CLI reference

Global flags

Persistent flags accepted by every command.

openobserve-cli auth

Log in, check identity and log out

openobserve-cli auth

openobserve-cli auth login

Store credentials for the active context (interactive)

openobserve-cli auth login

Prompts for the password (basic) or token, verifies it against the server, and stores it in the OS keychain. Requires an interactive terminal; in CI / agent sandboxes set OPENOBSERVE_EMAIL + OPENOBSERVE_PASSWORD or OPENOBSERVE_TOKEN instead.

openobserve-cli auth logout

Remove the stored credential for the active context

openobserve-cli auth logout

openobserve-cli auth status

Show the active identity and verify connectivity

openobserve-cli auth status

openobserve-cli config

Set up and inspect configuration and contexts

openobserve-cli config

openobserve-cli config contexts

List configured contexts and which one is current

openobserve-cli config contexts

openobserve-cli config init

Interactively configure a context and store credentials

openobserve-cli config init [flags]

Collects a server URL, organization and credentials, verifies them, then writes a named context plus the secret. With --pretty it runs an interactive TUI (requires a terminal); without it, a plain line-by-line wizard that also works over a pipe. When a configuration already exists, it first asks whether to edit a context, add a new one, or replace it all (skip the question with --context <name>). For fully headless setup, set OPENOBSERVE_URL / OPENOBSERVE_ORG / OPENOBSERVE_EMAIL / OPENOBSERVE_PASSWORD (or OPENOBSERVE_TOKEN) instead.

Options

Examples

  openobserve-cli config init --pretty   # interactive TUI (recommended)
  openobserve-cli config init             # plain line-by-line wizard (scripts, non-TTY)
  openobserve-cli config init --context prod   # add/update a named context directly

openobserve-cli config show

Show the resolved configuration with field provenance

openobserve-cli config show

openobserve-cli config use-context

Set the current context

openobserve-cli config use-context <name>

openobserve-cli doctor

Check configuration, credentials and connectivity

openobserve-cli doctor [flags]

Runs a quick health check: is a server configured, are credentials present, and can the server be reached and authenticated. Each check reports ok/failed so an agent can self-diagnose environment problems. It also reports whether a newer openobserve-cli release is available.

Options

Examples

  openobserve-cli doctor
  openobserve-cli doctor --no-update-check

openobserve-cli metrics

Query metrics with PromQL (instant and range)

openobserve-cli metrics

Metrics in OpenObserve are queried with PromQL, not SQL. `metrics query` evaluates an expression at a single instant; `metrics query-range` evaluates it across a time window at a step resolution (the shape you graph). Discover the metric names you can use with `stream list --type metrics`.

openobserve-cli metrics query

Evaluate a PromQL expression at a single instant

openobserve-cli metrics query [flags]

Runs an instant PromQL query. The result is a vector (one value per series) at the evaluation time, which defaults to now. Pass --query @file or --query @- to read a long expression from a file or stdin.

Options

Examples

  # current request rate per service
  openobserve-cli metrics query --query 'sum by (service)(rate(http_requests_total[5m]))'

  # evaluate at a past instant
  openobserve-cli metrics query --query 'up' --time 2024-01-02T15:04:05Z

openobserve-cli metrics query-range

Evaluate a PromQL expression across a time window

openobserve-cli metrics query-range [flags]

Runs a range PromQL query: the expression is evaluated at every --step between the start and end of the time range, yielding a matrix (a series of timestamped values per series) — the data behind a graph. The time range is required (--since or --from/--to).

Options

Examples

  # error rate over the last hour at 1-minute resolution
  openobserve-cli metrics query-range \
    --query 'sum(rate(http_requests_total{status=~"5.."}[5m]))' --since 1h --step 1m

openobserve-cli org

List organizations and set the default one

openobserve-cli org

Organizations scope every OpenObserve request. `org list` discovers the identifiers your credential can use; `org use` records one as the default so later commands need no --org.

openobserve-cli org list

List organizations the credential can access

openobserve-cli org list

openobserve-cli org use

Set the default organization in the active context

openobserve-cli org use <identifier>

openobserve-cli search

Run SQL searches over logs, metrics and traces

openobserve-cli search

Search is the heart of the CLI. `search run` returns matching rows; `search histogram` returns time-bucketed counts so you can see volume and shape before pulling raw rows; `search tail` follows a stream live. Time ranges are given in human form (--since 1h, or --from/--to); the CLI converts them to the microsecond epochs OpenObserve needs.

openobserve-cli search histogram

Return time-bucketed counts (the volume map before raw rows)

openobserve-cli search histogram [flags]

Runs a histogram(_timestamp, <interval>) aggregation so you can see how many rows fall in each time bucket — the shape of the data — before deciding which window to pull raw rows from with `search run`.

Options

Examples

  openobserve-cli search histogram --stream default --since 6h --interval 5m

openobserve-cli search run

Run a SQL query and return matching rows

openobserve-cli search run [flags]

Provide --stream to query a stream with an auto-built SELECT, optionally narrowed by --where; or provide a full --sql query (use --sql @file or --sql @- to read a long query from a file or stdin). The time range is required (--since or --from/--to). JSON output returns a summary plus the hits; --format ndjson streams one hit per line for piping. Use --all to page through every matching row as ndjson (bound it with --max).

Options

Examples

  # last hour of errors from the 'default' log stream
  openobserve-cli search run --stream default --where "level = 'ERROR'" --since 1h --limit 20

  # a full SQL query read from a file, over an explicit window
  openobserve-cli search run --sql @query.sql --since 24h

  # page through every matching row (streamed as ndjson)
  openobserve-cli search run --stream default --since 24h --all --max 50000

openobserve-cli search tail

Follow a stream live, printing new rows as they arrive

openobserve-cli search tail [flags]

Polls the stream on an interval and prints newly-arrived rows as ndjson, like `tail -f` for logs. It runs until interrupted (Ctrl-C). Use --since to backfill a window first; otherwise only rows arriving after start are shown.

Options

Examples

  # follow errors in the 'app' stream
  openobserve-cli search tail --stream app --where "level = 'ERROR'"

  # backfill the last 5 minutes, then follow
  openobserve-cli search tail --stream app --since 5m --interval 3s

openobserve-cli skill

Install the companion Skill for coding agents (Claude Code, Codex)

openobserve-cli skill

openobserve-cli skill install

Deploy the embedded Skill into a coding agent's skills directory

openobserve-cli skill install [flags]

Write the companion `openobserve` Skill — bundled inside this binary — into a coding agent's skills directory. With no flags it probes for installed agents (Claude Code, Codex) and installs into each one found. Re-run it after upgrading the CLI to refresh the Skill to the matching version.

Options

openobserve-cli skill path

Print where the Skill would be installed, and whether it is

openobserve-cli skill path [flags]

Options

openobserve-cli skill show

Print the embedded SKILL.md to stdout

openobserve-cli skill show

openobserve-cli skill status

Report whether the companion Skill is loaded and installed

openobserve-cli skill status [flags]

Options

openobserve-cli skill uninstall

Remove the companion Skill from a coding agent's skills directory

openobserve-cli skill uninstall [flags]

Delete a previously installed `openobserve` Skill. With no flags it probes for installed agents (Claude Code, Codex) and removes the Skill from each one found.

Options

openobserve-cli stream

Discover streams and inspect their schema

openobserve-cli stream

Streams are the logs / metrics / traces collections you query with `search`. List them to find names, then inspect a stream's schema to learn which columns exist before writing SQL.

openobserve-cli stream get

Get one stream including schema, settings and stats

openobserve-cli stream get <name> [flags]

Options

openobserve-cli stream list

List streams in the organization (the discovery map)

openobserve-cli stream list [flags]

Lists streams with their type and storage stats. Schema is omitted by default to keep the output a compact map; add --schema for full fields, or use `stream schema <name>` for one stream.

Options

openobserve-cli stream schema

Show just a stream's queryable columns and search settings

openobserve-cli stream schema <name> [flags]

Returns the stream's field schema plus its full-text-search and partition settings — what you need to write a correct SQL query.

Options

openobserve-cli stream stats

Show a stream's document count, time range and storage size

openobserve-cli stream stats <name> [flags]

Options

openobserve-cli trace

Search distributed traces and inspect a single trace

openobserve-cli trace

Traces are first-class in OpenObserve. `trace search` lists recent traces (newest first) with their duration and the services involved — the map for finding a slow or erroring request. `trace get <trace_id>` then reassembles every span of one trace into a parent/child waterfall. Discover trace stream names with `stream list --type traces`.

openobserve-cli trace get

Reassemble one trace into a span waterfall

openobserve-cli trace get <trace_id> [flags]

Fetches every span of a trace and assembles them into a parent/child tree, with each span's offset from the trace start so you can read it as a waterfall. JSON returns a nested tree; --format ndjson streams the spans flat, one per line. The time range must contain the trace.

Options

Examples

  openobserve-cli trace get 7be29a... --stream default --since 1h

openobserve-cli trace search

List recent traces in a trace stream

openobserve-cli trace search [flags]

Returns recent traces newest-first, each with its trace_id, duration and the services that participated — enough to pick which trace to inspect with `trace get`. Narrow the set with --filter (e.g. "duration > 1000000" for traces slower than 1s). The time range is required.

Options

Examples

  # slowest-first triage is done client-side; here, last hour of traces
  openobserve-cli trace search --stream default --since 1h --limit 20

  # only traces with an errored span
  openobserve-cli trace search --stream default --since 1h --filter "span_status = 'ERROR'"

openobserve-cli version

Print version information

openobserve-cli version