Metadata-Version: 2.4
Name: grapicli
Version: 0.5.0
Summary: A command-line tool for querying the Graylog API with rich terminal output
License-Expression: MIT
Keywords: graylog,cli,logging,search,devops,sysadmin
Author: Michael MacKenna
Author-email: mmackenna@unitedfiregroup.com
Requires-Python: >=3.14
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Provides-Extra: dev
Requires-Dist: mkdocs (>=1.6.0) ; extra == "dev"
Requires-Dist: mkdocs-material (>=9.5.0) ; extra == "dev"
Requires-Dist: pytest (>=8.0.0) ; extra == "dev"
Requires-Dist: pytest-cov (>=5.0.0) ; extra == "dev"
Requires-Dist: python-dotenv (>=1.0.0)
Requires-Dist: requests (>=2.32.0)
Requires-Dist: requests-mock (>=1.12.0) ; extra == "dev"
Requires-Dist: rich (>=13.0.0)
Requires-Dist: typer (>=0.24.1,<0.25.0)
Project-URL: Bug Tracker, https://github.com/mmackenna/grapicli/issues
Project-URL: Changelog, https://github.com/mmackenna/grapicli/blob/main/CHANGELOG.md
Project-URL: Documentation, https://mmackenna.github.io/grapicli
Project-URL: Homepage, https://github.com/mmackenna/grapicli
Project-URL: Repository, https://github.com/mmackenna/grapicli
Description-Content-Type: text/markdown

# grapicli

[![PyPI version](https://img.shields.io/pypi/v/grapicli.svg)](https://pypi.org/project/grapicli/)
[![Python 3.14+](https://img.shields.io/pypi/pyversions/grapicli.svg)](https://pypi.org/project/grapicli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Buy Me A Coffee](https://img.buymeacoffee.com/button-api/?text=Buy+me+a+coffee&emoji=☕&slug=mpmackenna&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://www.buymeacoffee.com/mpmackenna)

A command-line tool for querying the [Graylog](https://graylog.org) REST API, built with [Typer](https://typer.tiangolo.com/) and [Rich](https://github.com/Textualize/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](https://pypi.org/project/grapicli/) into a dedicated virtual environment.

### 1. Create a virtual environment

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

> **Tip:** If you manage multiple Python versions, use [pyenv](https://github.com/pyenv/pyenv) to install 3.14 first:
> ```bash
> pyenv install 3.14
> pyenv local 3.14
> python -m venv .venv && source .venv/bin/activate
> ```

### 2. Install from PyPI

```bash
pip install grapicli
```

Verify the installation:

```bash
grapicli --help
```

## Configuration

Create a `.env` file in your working directory with your Graylog credentials:

```bash
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:

```bash
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`

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

### Examples

```bash
# 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](https://python-poetry.org/):

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

### Running tests

```bash
poetry run pytest
```

Coverage report is written to `htmlcov/`.

### Building docs locally

```bash
poetry run mkdocs serve
```

## License

[MIT](https://opensource.org/licenses/MIT)


