libreclient¶

Async and sync Python client for the LibreNMS API.

Dual interface — use LibreClientAsync for async/await or LibreClientSync for traditional blocking calls.
Typed responses — all endpoints return Pydantic models with full IDE autocomplete.
Environment-driven config — configure via LIBRENMS_URL and LIBRENMS_TOKEN env vars or pass values directly.

Installation¶

pip install libreclient

Or with uv:

uv add libreclient

Quick Start¶

Synchronous¶

from libreclient import LibreClientSync

client = LibreClientSync(url="https://librenms.example.com", token="your-api-token")

# List all devices
response = client.devices.list_devices()
for device in response.devices:
    print(device["hostname"])

# Get a specific alert
alert = client.alerts.get_alert(42)

Asynchronous¶

import asyncio
from libreclient import LibreClientAsync


async def main():
    client = LibreClientAsync(url="https://librenms.example.com", token="your-api-token")

    response = await client.devices.list_devices()
    for device in response.devices:
        print(device["hostname"])

    await client.close()


asyncio.run(main())

Context Manager¶

# Sync
with LibreClientSync(url="https://librenms.example.com", token="your-api-token") as client:
    print(client.system.ping())

# Async
async with LibreClientAsync(url="https://librenms.example.com", token="your-api-token") as client:
    print(await client.system.ping())

Configuration¶

Configuration is handled by pydantic-settings. You can pass values directly or set environment variables:

Env Variable	Description	Default
`LIBRENMS_URL`	Base URL of your LibreNMS instance	(required)
`LIBRENMS_TOKEN`	API token (`X-Auth-Token`)	(required)
`LIBRENMS_VERIFY_SSL`	Verify TLS certificates	`true`
`LIBRENMS_API_VERSION`	API version path segment	`v0`

A .env file in your working directory is also supported. Copy the included sample to get started:

cp sample.env .env
# Edit .env with your LibreNMS URL and API token

Available Route Namespaces¶

All route namespaces are accessible as properties on the client:

Property	Description
`client.alerts`	Alert management and alert rules/templates
`client.arp`	ARP table lookups
`client.bills`	Billing data and graphs
`client.device_groups`	Device group management
`client.devices`	Device CRUD, discovery, components, graphs
`client.index`	List available API endpoints
`client.inventory`	Hardware inventory
`client.locations`	Location management
`client.logs`	Event, syslog, alert, and auth logs
`client.poller_groups`	Poller group info
`client.pollers`	Poller status
`client.port_groups`	Port group management
`client.port_security`	Port security (802.1X/MAB)
`client.ports`	Port info, search, and descriptions
`client.routing`	BGP, OSPF, VRF, MPLS, IPsec
`client.services`	Service monitoring
`client.switching`	VLANs, links, FDB, NAC
`client.system`	Ping and system info

License¶

MIT