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

grapicli requires Python 3.14 or newer. The recommended way to install is directly from PyPI into a dedicated virtual environment.

1. Create a virtual environment

python3.14 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

Tip: If you manage multiple Python versions, use pyenv to install 3.14 first:

pyenv install 3.14
pyenv local 3.14
python -m venv .venv && source .venv/bin/activate

2. Install from PyPI

pip install grapicli

Verify the installation:

grapicli --help

Configuration

Create a .env file in your working directory 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

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

Clone the repository and install with dev dependencies using Poetry:

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