greynoisecli

Typed Python client and command-line interface for the GreyNoise API

Overview

greynoisecli provides library and CLI access to all 68 operations registered from the current GreyNoise API reference. It supports structured queries, JSON request bodies, formatted responses, and streaming downloads without adding an SDK-specific abstraction for every endpoint.

Key Features

Supported Outputs

JSON responses    Pretty JSON, Rich tables, TOON 4.1
Text responses    Original text
Binary responses  Original bytes or streamed files
Library access    Parsed JSON values or raw response bytes

Installation

From PyPI (Recommended)

python3.14 -m pip install greynoisecli

From GitHub

python3.14 -m pip install "git+https://github.com/seifreed/greynoisecli.git"

From Source

git clone https://github.com/seifreed/greynoisecli.git
cd greynoisecli
python3.14 -m venv .venv

Activate the environment on Linux or macOS:

source .venv/bin/activate

Or on Windows PowerShell:

.venv\Scripts\Activate.ps1

Then install the package:

python -m pip install -e .

Configuration

Set the API key in the environment.

Linux or macOS:

export GREYNOISE="your-api-key"

Windows PowerShell:

$env:GREYNOISE = "your-api-key"

Alternatively, create greynoise/config.toml below $XDG_CONFIG_HOME, %APPDATA%, or ~/.config:

[greynoise]
api_key = "your-api-key"

Use GREYNOISE_CONFIG or the global --config option to select another file. The environment variable takes precedence over the configuration file.

Quick Start

# List every supported operation
greynoise operations

# Query the Community API
greynoise get-community-ip 8.8.8.8

# Query IP context with an optional parameter
greynoise v3-ip 8.8.8.8 --query quick=true

# Run a GNQL query and render a table
greynoise gnql-v3-query \
  --query "query=classification:malicious" \
  --query size=10 \
  --format table

Usage

Command Line Interface

Every OpenAPI operationId is available in kebab case. Path parameters are positional, query parameters use repeatable --query NAME=VALUE options, and request bodies use --data with inline JSON or @filename.

# Send a JSON request body
greynoise v3-multi-ip \
  --data '{"ips":["8.8.8.8","1.1.1.1"],"quick":true}'

# Export compact TOON for LLM context
greynoise gnql-v3-query \
  --query "query=classification:malicious" \
  --format toon \
  --output results.toon

# Stream a PCAP response
greynoise get-session-pcap SESSION_ID --output capture.pcap

# Select another documented response media type
greynoise post-psychic-model-download \
  --accept application/vnd.maxmind.maxmind-db \
  --output model.mmdb

Run greynoise COMMAND --help to see an operation's HTTP method, path, and available options.

Main Options

Python Library

GreyNoiseClient.call accepts either an OpenAPI operationId or its CLI name, so every registered operation shares one predictable interface.

from greynoisecli import ResponseOptions, create_client

client = create_client()  # GREYNOISE or the configuration file

community = client.call(
    "getCommunityIP",
    path={"ip": "8.8.8.8"},
)
print(community.json())

results = client.call(
    "gnql-v3-query",
    query={"query": "classification:malicious", "size": 10},
)
print(results.json())

with open("model.mmdb", "wb") as output:
    client.stream(
        "postPsychicModelDownload",
        ResponseOptions(
            accept="application/vnd.maxmind.maxmind-db",
            output=output,
        ),
        body={"model": "internet_scanner_intelligence"},
    )

Use GreyNoiseClient(api_key="...") when the caller already manages secrets. For an endpoint added after this package release, GreyNoiseClient.request can call its HTTP method and path directly.

Development

Install the package and the development dependency group declared in the same pyproject.toml file:

python3.14 -m pip install -e . --group dev

Run the project gates:

pytest --cov --cov-branch
black --check .
ruff check .
mypy .
bandit -r .
pip-audit

See ARCHITECTURE.md for module responsibilities and the dependency rule.

CI and Releases

CI runs the complete test, quality, and security gates on ubuntu-latest, windows-latest, and macos-latest. The same matrix must pass before a tagged release can be built.

Releases are published from tags that match the version in pyproject.toml:

# First update project.version in pyproject.toml and commit it.
git tag -a v0.1.0 -m "greynoisecli 0.1.0"
git push origin v0.1.0

The release workflow builds both the source distribution and wheel, then publishes them to PyPI with OIDC. It does not use a PyPI password or API token.

Before the first release, configure a pending Trusted Publisher in PyPI with:

Create the matching pypi environment in GitHub and restrict it to release tags before pushing the first version tag.

Requirements

• Python 3.14
• Windows, Linux, or macOS on x64 or ARM
• A GreyNoise API key for authenticated operations
• See pyproject.toml for the single runtime and development dependency declaration

Contributing

1. Fork the repository.
2. Create a feature branch: git switch -c feature/amazing-feature.
3. Add tests and run every quality and security gate.
4. Commit and push the branch.
5. Open a pull request.

Support the Project

If this project is useful in your workflows, you can support development:

Attribution

• Author: Marc Rivero Lopez | @seifreed
• Repository: github.com/seifreed/greynoisecli

_{Built for practical GreyNoise threat-intelligence workflows}