openobserve-cli 0.1.0__py3-none-any.whl

oo_cli/__init__.py

@@ -0,0 +1,3 @@
+"""CLI for the OpenObserve HTTP API."""
+
+__version__ = "0.1.0"

oo_cli/__main__.py

@@ -0,0 +1,4 @@
+from oo_cli.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

oo_cli/cli.py

@@ -0,0 +1,270 @@
+"""Command line entry point.
+
+Commands are a transcription of the API: `oo get dashboards` is
+`GET /api/{org}/dashboards`. Where the instance offers a v2 of an endpoint, the
+v2 one is used; the spec module decides that, there is no version switch.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import TextIO
+
+import httpx
+
+from oo_cli import __version__
+from oo_cli import spec as spec_module
+from oo_cli.client import Client, HTTPError, OOError
+from oo_cli.config import Config, ConfigError
+from oo_cli.timeutil import TimeError, to_micros
+
+VERBS = ("get", "post", "put", "patch", "delete")
+
+EPILOG = """\
+examples:
+  oo get dashboards
+  oo get alerts --folder default          -> /api/v2/{org}/alerts?folder=default
+  oo get streams/app_logs
+  oo post alerts -f alert.json
+  oo delete dashboards/0194f0e1 --folder default
+  oo search --sql "select * from default limit 10" --from -30m
+  oo api GET /api/{org}/prometheus/api/v1/query --query "up"
+
+environment:
+  OO_ENDPOINT    base URL, default http://localhost:5080
+  OO_ORG         organization, default "default"
+  OO_TOKEN       base64 of "email:token", sent as HTTP basic auth
+  OO_USER        alternative to OO_TOKEN, together with OO_PASSWORD
+  OO_COOKIE      Cookie header for a gateway in front of OpenObserve
+  OO_TIMEOUT     request timeout in seconds, default 60
+
+Any other --name value or --name=value is passed through as a query parameter.
+"""
+
+
+class UsageError(Exception):
+    pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        return run(sys.argv[1:] if argv is None else argv)
+    except UsageError as exc:
+        print(f"oo: {exc}", file=sys.stderr)
+        return 2
+    except (ConfigError, TimeError) as exc:
+        print(f"oo: {exc}", file=sys.stderr)
+        return 2
+    except HTTPError as exc:
+        print(f"oo: {exc}", file=sys.stderr)
+        _emit(exc.response, raw=False, stream=sys.stderr)
+        return 1
+    except OOError as exc:
+        print(f"oo: {exc}", file=sys.stderr)
+        return 1
+    except BrokenPipeError:
+        return 0
+
+
+def run(argv: list[str]) -> int:
+    parser = _parser()
+    args, extras = parser.parse_known_args(_glue_offsets(argv))
+    if not args.command:
+        parser.print_help()
+        return 2
+
+    config = Config.from_env(endpoint=args.endpoint, org=args.org, timeout=args.timeout)
+    with Client(config) as client:
+        if args.command == "spec":
+            return _run_spec(client, args, extras)
+        if args.command == "search":
+            return _run_search(client, args, extras)
+        if args.command == "api":
+            return _run_api(client, args, extras)
+        return _run_verb(client, args, extras)
+
+
+#: Options whose value starts with a minus (--from -30m), which argparse reads as an option.
+_OFFSET_OPTIONS = ("--from", "--to")
+
+
+def _glue_offsets(argv: list[str]) -> list[str]:
+    glued: list[str] = []
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        following = argv[index + 1] if index + 1 < len(argv) else None
+        if token in _OFFSET_OPTIONS and following is not None and following.startswith("-"):
+            glued.append(f"{token}={following}")
+            index += 2
+            continue
+        glued.append(token)
+        index += 1
+    return glued
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="oo",
+        description="Talk to the OpenObserve API.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+    )
+    parser.add_argument("--version", action="version", version=f"oo {__version__}")
+    parser.add_argument("--endpoint", help="OpenObserve base URL (env OO_ENDPOINT)")
+    parser.add_argument("--org", help="organization (env OO_ORG)")
+    parser.add_argument("--timeout", type=float, help="request timeout in seconds")
+    parser.add_argument("--raw", action="store_true", help="print the response body unformatted")
+
+    sub = parser.add_subparsers(dest="command")
+
+    for verb in VERBS:
+        p = sub.add_parser(
+            verb,
+            help=f"{verb.upper()} a resource, e.g. oo {verb} dashboards",
+            allow_abbrev=False,
+        )
+        p.add_argument(
+            "resource", help='resource path under the org, e.g. "alerts" or "alerts/<id>"'
+        )
+        _add_body_arguments(p)
+
+    p = sub.add_parser("api", help="call any path verbatim", allow_abbrev=False)
+    p.add_argument("method", help="HTTP method")
+    p.add_argument("path", help="full path, e.g. /api/default/streams")
+    _add_body_arguments(p)
+
+    p = sub.add_parser("search", help="run a SQL search", allow_abbrev=False)
+    p.add_argument("--sql", required=True, help="SQL query, e.g. select * from cloudwatch_logs")
+    p.add_argument("--from", dest="start", default="-1h", help="start time, default -1h")
+    p.add_argument("--to", dest="end", default="now", help="end time, default now")
+    p.add_argument("--size", type=int, default=100, help="number of rows, default 100")
+    p.add_argument("--offset", type=int, default=0, help="row offset, default 0")
+    p.add_argument("--type", default="logs", help="stream type: logs, metrics or traces")
+
+    p = sub.add_parser("spec", help="inspect the instance's OpenAPI document", allow_abbrev=False)
+    p.add_argument(
+        "action", choices=("paths", "refresh"), help="list endpoints or refetch the spec"
+    )
+    p.add_argument("needle", nargs="?", help="substring filter for paths")
+
+    return parser
+
+
+def _add_body_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("-d", "--data", help="request body, @file or @- for stdin")
+    parser.add_argument("-f", "--file", help="request body read from a file")
+
+
+def _run_verb(client: Client, args: argparse.Namespace, extras: list[str]) -> int:
+    segments = [s for s in args.resource.strip("/").split("/") if s]
+    if not segments:
+        raise UsageError("a resource is required, e.g. oo get dashboards")
+
+    spec = spec_module.load(client)
+    resolution = spec.resolve(client.config.org, segments, args.command)
+    if spec and not resolution.matched:
+        print(
+            f"oo: {args.command.upper()} {resolution.path} is not in the spec, sending it anyway",
+            file=sys.stderr,
+        )
+    response = client.request(
+        args.command, resolution.path, params=_params(extras), body=_body(args)
+    )
+    _emit(response, args.raw)
+    return 0
+
+
+def _run_api(client: Client, args: argparse.Namespace, extras: list[str]) -> int:
+    path = args.path if args.path.startswith("/") else "/" + args.path
+    response = client.request(args.method, path, params=_params(extras), body=_body(args))
+    _emit(response, args.raw)
+    return 0
+
+
+def _run_search(client: Client, args: argparse.Namespace, extras: list[str]) -> int:
+    body = {
+        "query": {
+            "sql": args.sql,
+            "start_time": to_micros(args.start),
+            "end_time": to_micros(args.end),
+            "from": args.offset,
+            "size": args.size,
+        }
+    }
+    params = [("type", args.type), *_params(extras)]
+    response = client.request(
+        "POST", f"/api/{client.config.org}/_search", params=params, body=json.dumps(body).encode()
+    )
+    _emit(response, args.raw)
+    return 0
+
+
+def _run_spec(client: Client, args: argparse.Namespace, extras: list[str]) -> int:
+    if extras:
+        raise UsageError(f"unexpected argument {extras[0]}")
+    spec = spec_module.load(client, refresh=args.action == "refresh")
+    if not spec:
+        raise OOError("could not read the OpenAPI document from the instance")
+    for path, methods in spec.paths(args.needle):
+        print(f"{' '.join(sorted(methods)).upper():<28} {path}")
+    return 0
+
+
+def _params(extras: list[str]) -> list[tuple[str, str]]:
+    """Turn leftover --name value / --name=value pairs into query parameters."""
+    params: list[tuple[str, str]] = []
+    index = 0
+    while index < len(extras):
+        token = extras[index]
+        if not token.startswith("--"):
+            raise UsageError(f"unexpected argument {token}")
+        name, _, value = token[2:].partition("=")
+        if not name:
+            raise UsageError(f"unexpected argument {token}")
+        if not _:
+            following = extras[index + 1] if index + 1 < len(extras) else None
+            if following is not None and not following.startswith("--"):
+                value = following
+                index += 1
+            else:
+                value = "true"
+        params.append((name, value))
+        index += 1
+    return params
+
+
+def _body(args: argparse.Namespace) -> bytes | None:
+    data: str | None = getattr(args, "data", None)
+    file: str | None = getattr(args, "file", None)
+    if data and file:
+        raise UsageError("use either -d or -f, not both")
+    if file:
+        data = "@" + file
+    if not data:
+        return None
+    if not data.startswith("@"):
+        return data.encode()
+    source = data[1:]
+    if source == "-":
+        return sys.stdin.buffer.read()
+    try:
+        with open(source, "rb") as handle:
+            return handle.read()
+    except OSError as exc:
+        raise UsageError(f"cannot read {source}: {exc}") from exc
+
+
+def _emit(response: httpx.Response, raw: bool, stream: TextIO = sys.stdout) -> None:
+    text = response.text
+    if not text.strip():
+        return
+    if not raw and "json" in response.headers.get("content-type", ""):
+        try:
+            text = json.dumps(response.json(), indent=2, ensure_ascii=False)
+        except ValueError:
+            pass
+    print(text, file=stream)

oo_cli/client.py

@@ -0,0 +1,95 @@
+"""Thin HTTP client for the OpenObserve API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from oo_cli.config import Config
+
+
+class OOError(Exception):
+    """Anything that should end the process with a message and a non-zero code."""
+
+
+class HTTPError(OOError):
+    def __init__(self, response: httpx.Response) -> None:
+        self.response = response
+        super().__init__(f"{response.status_code} {response.reason_phrase} {response.request.url}")
+
+
+class Client:
+    def __init__(self, config: Config) -> None:
+        self.config = config
+        headers = {"Accept": "application/json"}
+        if config.authorization:
+            headers["Authorization"] = config.authorization
+        if config.cookie:
+            headers["Cookie"] = config.cookie
+        self._http = httpx.Client(
+            base_url=config.endpoint,
+            headers=headers,
+            timeout=config.timeout,
+            follow_redirects=False,
+        )
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self._http.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        params: list[tuple[str, str]] | None = None,
+        body: bytes | None = None,
+    ) -> httpx.Response:
+        headers = {"Content-Type": "application/json"} if body is not None else None
+        try:
+            response = self._http.request(
+                method.upper(),
+                path,
+                # A tuple, because httpx types its list of pairs invariantly.
+                params=tuple(params) if params is not None else None,
+                content=body,
+                headers=headers,
+            )
+        except httpx.ConnectError as exc:
+            raise OOError(
+                f"{self.config.endpoint} is unreachable: {exc}\n{_UNREACHABLE_HINT}"
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise OOError(f"request to {self.config.endpoint}{path} failed: {exc}") from exc
+
+        _reject_gateway(response)
+        if response.status_code >= 400:
+            raise HTTPError(response)
+        return response
+
+    def json(self, method: str, path: str, **kwargs: Any) -> Any:
+        return self.request(method, path, **kwargs).json()
+
+
+_UNREACHABLE_HINT = "Set OO_ENDPOINT to a reachable OpenObserve, or start your port-forward."
+
+_GATEWAY_HINT = (
+    "Something in front of OpenObserve is authenticating users itself and only takes its\n"
+    "own session cookie, which no API token replaces. Copy the Cookie header out of the\n"
+    "browser that is signed in (devtools, Network tab) and pass it along:\n"
+    '  export OO_COOKIE="AWSELBAuthSessionCookie-0=...; AWSELBAuthSessionCookie-1=..."'
+)
+
+
+def _reject_gateway(response: httpx.Response) -> None:
+    """Explain a redirect to an identity provider instead of leaving a parse error behind."""
+    location = response.headers.get("location", "")
+    if not response.is_redirect or not location.startswith(("http://", "https://")):
+        return
+    if httpx.URL(location).host == response.request.url.host:
+        return
+    raise OOError(
+        f"{response.request.url} redirected to {httpx.URL(location).host}\n{_GATEWAY_HINT}"
+    )

oo_cli/config.py

@@ -0,0 +1,62 @@
+"""Endpoint, organization and credentials, all from the environment."""
+
+from __future__ import annotations
+
+import base64
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+DEFAULT_ENDPOINT = "http://localhost:5080"
+DEFAULT_ORG = "default"
+DEFAULT_TIMEOUT = 60.0
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Config:
+    endpoint: str
+    org: str
+    authorization: str | None
+    cookie: str | None
+    timeout: float
+
+    @classmethod
+    def from_env(
+        cls,
+        env: Mapping[str, str] | None = None,
+        endpoint: str | None = None,
+        org: str | None = None,
+        timeout: float | None = None,
+    ) -> Config:
+        values: Mapping[str, str] = os.environ if env is None else env
+        return cls(
+            endpoint=(endpoint or values.get("OO_ENDPOINT") or DEFAULT_ENDPOINT).rstrip("/"),
+            org=org or values.get("OO_ORG") or DEFAULT_ORG,
+            authorization=_authorization(values),
+            cookie=values.get("OO_COOKIE") or None,
+            timeout=timeout or float(values.get("OO_TIMEOUT") or DEFAULT_TIMEOUT),
+        )
+
+
+def _authorization(env: Mapping[str, str]) -> str | None:
+    """Build the Authorization header value.
+
+    OO_TOKEN is the credential OpenObserve hands out for a service account (base64
+    of "email:token"); it is sent as-is when it already names its scheme.
+    OO_USER + OO_PASSWORD is the same thing spelled out.
+    """
+    token = env.get("OO_TOKEN")
+    if token:
+        token = token.strip()
+        return token if " " in token else f"Basic {token}"
+
+    user, password = env.get("OO_USER"), env.get("OO_PASSWORD")
+    if user and password:
+        return "Basic " + base64.b64encode(f"{user}:{password}".encode()).decode()
+    if user or password:
+        raise ConfigError("OO_USER and OO_PASSWORD have to be set together")
+    return None

oo_cli/spec.py

@@ -0,0 +1,129 @@
+"""The instance's own OpenAPI document, used to route a command to v1 or v2.
+
+OpenObserve serves its spec at /api-doc/openapi.json, so the command surface follows
+whatever version is deployed instead of a table we would have to maintain by hand.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from oo_cli.client import Client, OOError
+
+SPEC_PATH = "/api-doc/openapi.json"
+MAX_AGE_SECONDS = 7 * 24 * 3600
+
+#: Resources that exist in both versions; used when the spec cannot be fetched.
+V2_RESOURCES = frozenset({"alerts", "folders", "reports"})
+
+_METHODS = ("get", "post", "put", "patch", "delete", "head", "options")
+
+
+@dataclass(frozen=True)
+class Resolution:
+    path: str
+    template: str | None
+
+    @property
+    def matched(self) -> bool:
+        return self.template is not None
+
+
+class Spec:
+    def __init__(self, templates: dict[str, list[str]]) -> None:
+        self.templates = templates
+
+    def __bool__(self) -> bool:
+        return bool(self.templates)
+
+    def resolve(self, org: str, segments: list[str], method: str) -> Resolution:
+        """Map command segments onto a concrete API path, preferring v2.
+
+        A few endpoints (organizations, clusters) sit outside an organization, so an
+        org-less path is the last candidate.
+        """
+        tail = "/".join(segments)
+        v2, v1, global_ = f"/api/v2/{org}/{tail}", f"/api/{org}/{tail}", f"/api/{tail}"
+
+        if not self.templates:
+            return Resolution(v2 if segments and segments[0] in V2_RESOURCES else v1, None)
+
+        for candidate in (v2, v1, global_):
+            template = self._match(candidate, method)
+            if template:
+                return Resolution(candidate, template)
+        return Resolution(v1, None)
+
+    def _match(self, path: str, method: str) -> str | None:
+        parts = path.strip("/").split("/")
+        for template, methods in self.templates.items():
+            if method.lower() not in methods:
+                continue
+            template_parts = template.strip("/").split("/")
+            if len(template_parts) != len(parts):
+                continue
+            if all(
+                t.startswith("{") and t.endswith("}") or t == p
+                for t, p in zip(template_parts, parts, strict=True)
+            ):
+                return template
+        return None
+
+    def paths(self, needle: str | None = None) -> list[tuple[str, list[str]]]:
+        items = sorted(self.templates.items())
+        if needle:
+            items = [(p, m) for p, m in items if needle.lower() in p.lower()]
+        return items
+
+
+def load(client: Client, refresh: bool = False) -> Spec:
+    """Return the cached spec, fetching it when missing, stale or forced."""
+    cache = _cache_file(client.config.endpoint)
+    if not refresh:
+        cached = _read_cache(cache)
+        if cached is not None:
+            return Spec(cached)
+
+    try:
+        document = client.json("GET", SPEC_PATH)
+    except OOError:
+        cached = _read_cache(cache, ignore_age=True)
+        return Spec(cached if cached is not None else {})
+
+    templates = {
+        path: [m for m in operations if m in _METHODS]
+        for path, operations in document.get("paths", {}).items()
+    }
+    _write_cache(cache, client.config.endpoint, templates)
+    return Spec(templates)
+
+
+def _cache_file(endpoint: str) -> Path:
+    base = os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache"
+    digest = hashlib.sha1(endpoint.encode(), usedforsecurity=False).hexdigest()[:12]
+    return Path(base) / "oo-cli" / f"spec-{digest}.json"
+
+
+def _read_cache(path: Path, ignore_age: bool = False) -> dict[str, list[str]] | None:
+    try:
+        payload = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return None
+    if not ignore_age and time.time() - payload.get("fetched_at", 0) > MAX_AGE_SECONDS:
+        return None
+    templates = payload.get("templates")
+    return templates if isinstance(templates, dict) else None
+
+
+def _write_cache(path: Path, endpoint: str, templates: dict[str, list[str]]) -> None:
+    payload = {"endpoint": endpoint, "fetched_at": time.time(), "templates": templates}
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(payload))
+    except OSError:
+        pass

oo_cli/timeutil.py

@@ -0,0 +1,51 @@
+"""Time arguments. OpenObserve takes epoch microseconds everywhere."""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime, timedelta
+
+_OFFSET = re.compile(r"^([+-])(\d+)([smhdw])$")
+_UNITS = {"s": "seconds", "m": "minutes", "h": "hours", "d": "days", "w": "weeks"}
+
+
+class TimeError(ValueError):
+    pass
+
+
+def to_micros(value: str, now: datetime | None = None) -> int:
+    """Parse "now", an offset like -15m, epoch seconds/millis/micros, or ISO 8601.
+
+    A timestamp without a zone is read as local time.
+    """
+    now = now or datetime.now(UTC)
+    value = value.strip()
+
+    if value == "now":
+        return int(now.timestamp() * 1_000_000)
+
+    offset = _OFFSET.match(value)
+    if offset:
+        sign, amount, unit = offset.groups()
+        delta = timedelta(**{_UNITS[unit]: int(amount)})
+        moment = now - delta if sign == "-" else now + delta
+        return int(moment.timestamp() * 1_000_000)
+
+    if value.isdigit():
+        digits = len(value)
+        if digits <= 11:
+            return int(value) * 1_000_000
+        if digits <= 14:
+            return int(value) * 1_000
+        return int(value)
+
+    try:
+        moment = datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise TimeError(
+            f"cannot read {value!r} as a time: use now, an offset (-15m, -2h, -7d), "
+            "an epoch timestamp or an ISO 8601 datetime"
+        ) from exc
+    if moment.tzinfo is None:
+        moment = moment.astimezone()
+    return int(moment.timestamp() * 1_000_000)

openobserve_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: openobserve-cli
+Version: 0.1.0
+Summary: CLI for the OpenObserve HTTP API
+Project-URL: Homepage, https://github.com/paveldedik/oo-cli
+Project-URL: Repository, https://github.com/paveldedik/oo-cli
+Project-URL: Issues, https://github.com/paveldedik/oo-cli/issues
+Author-email: Pavel Dedík <dedikx@gmail.com>
+Maintainer-email: Pavel Dedík <dedikx@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,logs,metrics,observability,openobserve,traces
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# oo
+
+A small CLI for the OpenObserve HTTP API. Commands are a transcription of the API rather
+than a model of it: `oo get dashboards` is `GET /api/{org}/dashboards`, and anything the
+CLI does not know about is still reachable with `oo api`.
+
+```bash
+oo get dashboards
+oo get alerts --folder default           # GET /api/v2/{org}/alerts?folder=default
+oo get streams/app_logs
+oo post alerts -f alert.json
+oo put dashboards/0194f0e1 -d @- < dashboard.json
+oo delete alerts/7
+
+oo search --sql "select * from default limit 10" --from -30m
+oo api GET /api/default/prometheus/api/v1/query --query "up"
+```
+
+Any `--name value` or `--name=value` the CLI does not define becomes a query parameter.
+`-d` takes a literal body, `@file` or `@-` for stdin; `-f file` is shorthand for `-d @file`.
+Output is pretty-printed JSON on stdout, errors on stderr, exit code 1 on HTTP >= 400 and
+2 on a bad command.
+
+Times accept `now`, an offset (`-15m`, `-2h`, `-7d`), an epoch timestamp in seconds,
+milliseconds or microseconds, or an ISO 8601 datetime (local time when it carries no zone).
+
+## Install
+
+```bash
+uv tool install openobserve-cli     # installs the `oo` command
+uvx openobserve-cli get streams     # or run it without installing anything
+```
+
+The command is `oo`; `openobserve-cli` is the same command under the distribution's
+name, which is what makes the `uvx` one-liner work. From a checkout: `uv sync` and
+then `uv run oo --help`.
+
+## Configuration
+
+Everything comes from the environment. Nothing is required: with no variables set the
+CLI talks to `http://localhost:5080` as an anonymous user, which is what a port-forward
+to a local OpenObserve looks like.
+
+| Variable                  | Required                        | Default                 | Meaning                                       |
+|---------------------------|---------------------------------|-------------------------|-----------------------------------------------|
+| `OO_ENDPOINT`             | optional                        | `http://localhost:5080` | base URL                                      |
+| `OO_ORG`                  | optional                        | `default`               | organization                                  |
+| `OO_TOKEN`                | to reach anything but `/healthz`| —                       | base64 of `email:token`, sent as basic auth   |
+| `OO_USER` / `OO_PASSWORD` | instead of `OO_TOKEN`           | —                       | the same credential spelled out               |
+| `OO_COOKIE`               | when a gateway guards the host  | —                       | `Cookie` header, sent verbatim                |
+| `OO_TIMEOUT`              | optional                        | `60`                    | request timeout in seconds                    |
+
+`--endpoint`, `--org` and `--timeout` override the corresponding variable.
+
+## When something authenticates in front of OpenObserve
+
+Plenty of deployments put OpenObserve behind a gateway that authenticates users itself:
+an AWS ALB with an `authenticate-oidc` action, oauth2-proxy, an identity-aware proxy.
+Such a gateway takes nothing but its own session cookie, which it issues to a browser
+at the end of an interactive login — no API token gets past it, and a CLI cannot run
+that flow on its own.
+
+So hand it the cookie your browser already has. In devtools, Network tab, take the
+`Cookie` header off any request to that host (or Application, Cookies) and:
+
+```bash
+export OO_COOKIE="AWSELBAuthSessionCookie-0=...; AWSELBAuthSessionCookie-1=..."
+```
+
+It is sent verbatim, so any gateway's cookie works, whatever it calls it. A request
+that hits the gateway without one says so instead of failing on a page of HTML. The
+cookie expires on the gateway's schedule — an ALB session lasts 7 days by default.
+
+The gateway is orthogonal to OpenObserve's own authentication: the cookie gets you
+through the door, `OO_TOKEN` still identifies you to OpenObserve.
+
+## v1 and v2
+
+Where an endpoint exists in both versions, v2 is used; there is no version switch. The CLI
+reads the instance's own OpenAPI document (`/api-doc/openapi.json`) to decide, so it follows
+whatever is deployed. The document is cached per endpoint under `~/.cache/oo-cli` for a week.
+
+```bash
+oo spec paths alerts     # list endpoints and their methods
+oo spec refresh          # refetch after an OpenObserve upgrade
+```
+
+Without a reachable spec the CLI falls back to v1, except for `alerts`, `folders` and
+`reports`, the three resources that have a v2 in OpenObserve 0.91.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+pre-commit install     # ruff, mypy and conventional commit messages
+```

openobserve_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+oo_cli/__init__.py,sha256=YcD1_uucpne7GDvgTXRgAQiVsAUedeDhQzwCgKFB5K0,63
+oo_cli/__main__.py,sha256=o8s9A9y8gskRoF0tCDFf7FnZk2DpuiIMLJywOILMcdc,85
+oo_cli/cli.py,sha256=XkZu_9M0olJUZHfT4cqphOyozG8zDUucabLHbOS9wys,9655
+oo_cli/client.py,sha256=mtASFEn3FpBSdPgvSWElQHjWJy8gJVi0X6u_eqNBGyo,3246
+oo_cli/config.py,sha256=IJqEBdtOGJwkDHgKgqY7bdKTAsxpG0UD3a6Cc706HKM,1892
+oo_cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oo_cli/spec.py,sha256=ZnB1ycDF-GZzpi5Cy5nlom__ZM3oaiNvcfM72pPh3r4,4369
+oo_cli/timeutil.py,sha256=OF3RgKioTxSk4HBv_vM6fahrtsdkbziwHqxq-AlcuFM,1541
+openobserve_cli-0.1.0.dist-info/METADATA,sha256=W97OBNEciUPPodnDaVLixWkx2j00rAL0_fFbvXNg4Zw,5536
+openobserve_cli-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+openobserve_cli-0.1.0.dist-info/entry_points.txt,sha256=llEuSqDhLj39jPaxdEV8T6bZ7buc_ARx7fI0AyVfKec,73
+openobserve_cli-0.1.0.dist-info/licenses/LICENSE,sha256=sSY9MDyhGmQeG4gJx-wbK8XRLnNyE54hRoEz4jjDEwI,1072
+openobserve_cli-0.1.0.dist-info/RECORD,,

openobserve_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

openobserve_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+oo = oo_cli.cli:main
+openobserve-cli = oo_cli.cli:main

openobserve_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skip Pay s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.