grapicli 0.3.0

A command-line tool for querying the Graylog API with rich terminal output

grapicli

A command-line tool for querying the Graylog REST API, built with Typer and Rich.

Features

• 🔍 Search logs by source host, message content, or any combination
• 🕐 Flexible time ranges — relative (last N minutes) or absolute (--since / --until)
• 📋 Configurable result limits with --limit
• 🔑 Token-based authentication loaded automatically from a .env file
• 🖥️ Rich terminal output — results displayed in a colour-coded table

Installation

pip install grapicli

Or with Poetry:

poetry add grapicli

Configuration

Create a .env file in your working directory (or project root) with your Graylog credentials:

export GRAYLOG_URL=https://your-graylog-server
export GRAYLOG_TOKEN=your_api_token_here

Note: Never commit your .env file to version control.

Finding your API token

1. Log in to the Graylog web interface.
2. Go to System → Users and Teams → Edit Profile → API Tokens.
3. Create a new token and copy the value into your .env file.

Usage

grapicli search [OPTIONS]

Options

Flag	Short	Type	Default	Description
--source	-s	TEXT	—	Filter by source host or identifier
--message	-m	TEXT	—	Filter by message text (Lucene substring match)
--limit	-n	INT	30	Maximum number of messages to return
--last	-l	INT	15	Return messages from the last N minutes
--since	-S	TEXT	—	Start of an absolute time range
--until	-U	TEXT	—	End of an absolute time range (defaults to now)

Time range

Relative (default) — returns messages from the last 15 minutes:

grapicli search
grapicli search --last 60   # last hour

Absolute — --since and/or --until switch to an exact range. All times are UTC.

Accepted formats: YYYY-MM-DD HH:MM:SS · YYYY-MM-DDTHH:MM:SS · YYYY-MM-DD HH:MM · YYYY-MM-DD

grapicli search --since "2026-04-17 08:00:00" --until "2026-04-17 09:00:00"

Examples

# Default: last 15 minutes, up to 30 messages
grapicli search

# Filter by source host
grapicli search --source myserver

# Filter by message text and increase result count
grapicli search --message "error" --limit 100

# Last hour
grapicli search --last 60

# Absolute range
grapicli search --since "2026-04-17 08:00:00" --until "2026-04-17 09:00:00"

# Combine source, message filter, and time range
grapicli search --source myserver --message "timeout" --since "2026-04-17 12:00:00"

Output

Query: source:"myserver"  Matches: 4821  Showing: 30/30
┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Timestamp                ┃ Source     ┃ Message                            ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 2026-04-17T10:00:01.000Z │ myserver   │ Service started successfully       │
│ 2026-04-17T10:00:02.000Z │ myserver   │ Connected to database              │
└──────────────────────────┴────────────┴────────────────────────────────────┘

Development

git clone https://github.com/mmackenna/grapicli.git
cd grapicli
poetry install --extras dev

Running tests

poetry run pytest

Coverage report is written to htmlcov/.

Building docs locally

poetry run mkdocs serve

License

MIT