Installation

Prerequisites

• Python 3.14 or newer — grapicli uses features introduced in Python 3.14. Check your version with python3 --version.

Install from PyPI (recommended)

No need to clone the repository for normal usage. Install directly from PyPI into a dedicated virtual environment.

1. Create a virtual environment

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

Your shell prompt will show (.venv) to confirm the environment is active.

Managing multiple Python versions with pyenv

If Python 3.14 is not your system default, install and select it with pyenv:

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

2. Install grapicli

pip install grapicli

3. Verify the installation

grapicli --help

You should see the help output listing the search command and its options.

---

Configuration

grapicli reads credentials from a .env file in your current working directory when you run the command.

Create .env with the following variables:

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

Finding your API token

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

Warning

Never commit your .env file to version control. Add it to .gitignore:

echo '.env' >> .gitignore

---

Upgrading

To upgrade to the latest version:

pip install --upgrade grapicli

---

Development installation

If you want to contribute or run the test suite, install from source using Poetry:

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

This adds:

Tool	Purpose
pytest	Test runner
pytest-cov	Coverage reporting
requests-mock	HTTP mocking in tests
mkdocs	Documentation site generator
mkdocs-material	Material theme for MkDocs

Run tests:

poetry run pytest

Serve docs locally:

poetry run mkdocs serve