obs

One CLI for infrastructure context, built for humans and AI agents.

obs is an observability CLI designed to give agents the exact infrastructure context they need without saturating the model window. The project starts with logs on Loki, but the repository is structured for future expansion into metrics, traces, alerts, and multiple providers.

The design is inspired by the machine-first patterns in googleworkspace/cli: structured stdout, schema introspection, dry-run previews, stable exit codes, and helper commands prefixed with +.

This project is not affiliated with Google, Grafana, or Loki.

Why obs

• Machine-first stdout: commands return stable JSON by default and reserve stderr for hints and logs.
• Bounded context for agents: use schema, doctor, query, tail --max-polls, and helper commands instead of pasting dashboards into prompts.
• Safe automation: dry-run previews, stable exit codes, config precedence, and secret redaction are first-class.
• Scalable architecture: provider abstraction, command contracts, docs, CI, release automation, and tests are baked in from day one.

Current Scope

• Signal type: logs
• Provider: Loki
• Roadmap: metrics, traces, alerts, additional providers, richer helpers, generated agent skills

Installation

From source:

go install github.com/jdiegosierra/agent-observability-cli/cmd/obs@latest

Or clone the repo and build locally:

git clone https://github.com/jdiegosierra/agent-observability-cli.git
cd agent-observability-cli
make build

Quick Start

Set the minimum environment:

export OBS_LOKI_URL="https://loki.example.com"
export OBS_LOKI_AUTH_MODE="bearer"
export OBS_LOKI_TOKEN="replace-me"

Then run:

obs doctor
obs schema
obs labels list --since 24h
obs query logs --selector '{app="api"} |= "error"' --since 30m
obs tail logs --selector '{namespace="prod"}' --since 5m --max-polls 3 --output ndjson
obs loki +recent-errors --selector '{service="payments"}' --since 15m
obs loki +incident-window --selector '{app="api"}' --at 2026-03-24T10:15:00Z

Command Surface

Primitive commands:

• obs query logs
• obs tail logs
• obs labels list
• obs labels values
• obs series list
• obs schema
• obs doctor
• obs profile list|get|use
• obs version

Helper commands:

• obs loki +recent-errors
• obs loki +incident-window

AI Agent Workflow

Recommended sequence for agent-driven debugging:

1. obs doctor to validate config and connectivity.
2. obs schema or obs schema command query.logs to inspect contracts instead of guessing flags.
3. obs query logs --dry-run ... to preview the provider request without network calls.
4. obs query logs ... --output json for bounded incident context.
5. obs tail logs ... --max-polls N --output ndjson when incremental updates are needed.
6. obs loki +incident-window ... for focused before/after context around an event.

Additional agent-specific guidance lives in AGENTS.md, docs/agent-guide.md, and skills/.

Configuration

Config precedence is explicit:

1. CLI flags
2. Environment variables
3. Selected profile in config.yaml
4. Default profile and built-in defaults

Default config path:

~/.config/obs/config.yaml

Example config:

default_provider: loki
default_profile: dev

profiles:
  dev:
    provider: loki
    loki:
      url: https://loki.example.com
      tenant_id: team-a
      auth_mode: bearer
      token_env: OBS_LOKI_TOKEN
      timeout: 15s
      default_limit: 200
      default_since: 1h

Copy-paste templates:

• .env.example
• examples/config.yaml

Output Contract

• Default output: json
• Streaming-friendly output: ndjson
• Also supported: yaml, table, csv
• Success payloads go to stdout
• Errors are structured and go to stdout
• Hints and structured runtime logs go to stderr

Example query response:

{
  "provider": "loki",
  "query_type": "range",
  "range": {
    "from": "2026-03-24T10:00:00Z",
    "to": "2026-03-24T11:00:00Z"
  },
  "streams": [
    {
      "labels": {
        "app": "api",
        "namespace": "prod"
      },
      "entries": [
        {
          "ts": "2026-03-24T10:15:00Z",
          "line": "request failed"
        }
      ]
    }
  ]
}

Exit Codes

Code	Meaning
0	success
1	provider or API error
2	auth error
3	validation or usage error
4	unsupported capability or schema
5	connectivity error
6	timeout or cancellation
7	internal error

Architecture

Core layout:

• cmd/obs/ entrypoint
• internal/cli/ Cobra command surface and runtime wiring
• internal/config/ config loading, precedence, profiles, redaction
• internal/provider/ stable domain contracts
• internal/provider/loki/ Loki implementation
• internal/providers/ provider registry and factory
• internal/output/ JSON, NDJSON, YAML, table, CSV renderers
• internal/schema/ command and provider contracts for agents
• internal/validate/ time range and flag validation

More detail in docs/architecture.md.

Development

make fmt
make test
make build

Manual smoke checks:

go run ./cmd/obs schema
go run ./cmd/obs version --output table
go run ./cmd/obs doctor --dry-run

Open Source

• License: Apache-2.0
• Issues and PRs welcome
• The initial implementation focuses on long-term maintainability rather than squeezing every Loki option into flags on day one