Skip to content

API Reference

This page documents the internal Python modules that make up grapicli.

grapicli.config

Configuration helpers that load credentials from the .env file.

get_graylog_url() -> str

Returns the value of GRAYLOG_URL from the environment, with any trailing slash stripped.

Raises ValueError if the variable is not set.

get_graylog_token() -> str

Returns the value of GRAYLOG_TOKEN from the environment.

Raises ValueError if the variable is not set.

grapicli.client

GraylogClient

A thin wrapper around the Graylog REST API using a requests.Session with token-based basic authentication (username = token value, password = "token").

__init__()

Reads credentials from the environment via grapicli.config and configures the session.

search_relative(query, range_seconds, limit, fields=None, sort=None) -> dict

Search using a relative time range.

Parameter Type Description
query str Lucene query string (e.g. *, source:"host")
range_seconds int How many seconds back from now to search
limit int Maximum number of messages to return
fields str \| None Comma-separated list of fields to return
sort str \| None Sort field and order (e.g. timestamp:desc)

Returns the parsed JSON response dict. Raises requests.HTTPError on non-2xx responses.

search_absolute(query, from_dt, to_dt, limit, fields=None, sort=None) -> dict

Search using an absolute time range.

Parameter Type Description
query str Lucene query string
from_dt datetime Start of the range (naive datetimes assumed UTC)
to_dt datetime End of the range
limit int Maximum number of messages to return
fields str \| None Comma-separated list of fields to return
sort str \| None Sort field and order

Returns the parsed JSON response dict. Raises requests.HTTPError on non-2xx responses.

grapicli.main

Typer CLI application. Entry point: grapicli.main:app.

The search subcommand. See Usage for the full option reference.

_build_query(source, message) -> str

Builds a Lucene query string from optional filter values.

Input Output
(None, None) *
("myhost", None) source:"myhost"
(None, "error") message:"error"
("myhost", "error") source:"myhost" AND message:"error"

_parse_datetime(value) -> datetime

Parses a datetime string in one of four accepted formats and returns a UTC-aware datetime. Raises typer.BadParameter if none of the formats match.