Pre-release

This release is a pre-release and may not be stable for production use.

cribl-python-sdk

Python SDK for the Cribl Control Plane API and the Cribl.Cloud platform (management) API.

Two OpenAPI files, one client — do not merge the specs:

Surface	Spec	Host	SDK
Control plane	`openapi/control-plane.yml` (v4.20.0)	Your origin (`server_url`)	`cribl.pipelines`, `cribl.sources`, … — SDK appends `/api/v1`
Cribl.Cloud platform	`openapi/management-plane.yml`	Gateway (`https://gateway.cribl.cloud` by default)	`cribl.cloud.*` — paths as in the spec (`/v1/organizations/…`)

Same Security (OAuth2 client credentials) for both Cloud hosts. On-prem username/password authenticates the control plane only.

Install

uv

uv add cribl-python-sdk

pip

pip install cribl-python-sdk

poetry

poetry add cribl-python-sdk

Shell and script usage with uv

Use in a Python shell:

uvx --from cribl-python-sdk python

Standalone script without a project:

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.14"
# dependencies = [
#     "cribl-python-sdk",
# ]
# ///

from cribl_python_sdk import Cribl, Security

cribl = Cribl(
    server_url="http://localhost:9000",
    security=Security(username="admin", password="admin"),
)
print(cribl.health.get().data.status)

Run with uv run script.py.

Authentication

The SDK handles token acquisition and refresh automatically — pass credentials once and the client manages the rest.

On-Prem (username/password)

The client calls POST /auth/login internally, stores the JWT, and refreshes it before expiry.

from cribl_python_sdk import Cribl, Security

cribl = Cribl(
    server_url="http://localhost:9000",
    security=Security(username="admin", password="admin"),
)

pipelines = cribl.pipelines.list()
print(f"Found {pipelines.data.count} pipeline(s)")

cribl.close()

Cloud — Control Plane (OAuth2)

OAuth2 client credentials flow. The SDK fetches and refreshes the access token automatically.

from cribl_python_sdk import Cribl, Security

cribl = Cribl(
    server_url="https://main-your-org.cribl.cloud",
    security=Security(client_id="…", client_secret="…"),
)

pipelines = cribl.pipelines.list()
routes = cribl.routes.list()

cribl.close()

Cloud — Management Plane (`cribl.cloud.*`)

Same client, same credentials. Management plane operations live under the cribl.cloud.* namespace and route to the gateway (https://gateway.cribl.cloud by default).

from cribl_python_sdk import Cribl, Security

cribl = Cribl(
    server_url="https://main-your-org.cribl.cloud",
    security=Security(client_id="…", client_secret="…"),
)

# Management plane
workspaces = cribl.cloud.workspaces.list(organization_id="your-org")
health = cribl.cloud.health.get()

# Control plane (same client)
pipelines = cribl.pipelines.list()

cribl.close()

Pre-existing Bearer Token

If you already have a token (e.g. from an external auth flow), pass it directly — no auto-login or refresh:

from cribl_python_sdk import Cribl, Security

cribl = Cribl(
    server_url="https://main-your-org.cribl.cloud",
    security=Security(bearer_auth="your-token"),
)

pipelines = cribl.pipelines.list()
workspaces = cribl.cloud.workspaces.list(organization_id="your-org")

cribl.close()

Quickstart

from cribl_python_sdk import Cribl, Security

cribl = Cribl(
    server_url="http://localhost:9000",
    security=Security(username="admin", password="admin"),
)

# List pipelines (sync)
pipelines = cribl.pipelines.list()

# Async variant
pipelines = await cribl.pipelines.list_async()

# Scoped to a worker group (control plane only — not cribl.cloud.*)
wg = cribl.in_context(group_id="default")
sources = wg.sources.list()

See examples/ for more usage patterns.

Scoped Client

Instead of manually constructing group/node URLs, use in_context():

# Control-plane calls route to /api/v1/m/{group_id} automatically.
# cribl.cloud.* is unchanged (still the gateway).
wg = cribl.in_context(group_id="my_fleet")
sources = wg.sources.list()
destinations = wg.destinations.list()
pipelines = wg.pipelines.list()

# Also works as context manager
with cribl.in_context(group_id="my_fleet") as wg:
    sources = wg.sources.list()

Creating Resources

from cribl_python_sdk import Cribl, Security
from cribl_python_sdk.models.inputs import InputSyslog

# Pipelines use explicit kwargs
cribl.pipelines.create(id="my_pipe", conf={"functions": []})

# Sources/Destinations/Collectors accept a typed model or plain dict
wg.sources.create(InputSyslog(id="syslog:in", host="0.0.0.0", port=514))
wg.sources.create({"id": "syslog:in", "type": "syslog", "host": "0.0.0.0", "port": 514})

Environment Variables

Variable	Description
`CRIBL_SERVER_URL`	On-prem server origin (e.g. `http://localhost:9000`)
`CRIBL_USERNAME`	On-prem login username
`CRIBL_PASSWORD`	On-prem login password
`CRIBL_CLOUD_URL`	Cribl.Cloud workspace origin for the control plane (e.g. `https://main-your-org.cribl.cloud`)
`CRIBL_CLOUD_GATEWAY_URL`	Platform/mgmt gateway override (default: `https://gateway.cribl.cloud`)
`CRIBL_CLIENT_ID`	OAuth2 client ID (Cloud control plane + `cribl.cloud.*`)
`CRIBL_CLIENT_SECRET`	OAuth2 client secret (Cloud control plane + `cribl.cloud.*`)
`CRIBL_AUDIENCE`	OAuth2 audience (default: `https://api.cribl.cloud` from spec)
`CRIBL_TOKEN_URL`	OAuth2 token endpoint (default: `https://login.cribl.cloud/oauth/token` from spec)
`CRIBL_WORKER_GROUP_ID`	Target worker group ID
`CRIBL_ORGANIZATION_ID`	Cribl.Cloud organization id for `cribl.cloud.*` examples
`CRIBL_SDK_DEBUG`	Set to `true` to enable debug logging (zero-code activation)

Available Resources and Operations

All methods have sync + async variants (append _async to method name).

Available methods

Cloud

Cribl.Cloud platform API (openapi/management-plane.yml). Calls use the gateway, not /api/v1.

Cloud.Health

get - Get the health status of the application

Cloud.ApiCredentials

list - List API Credentials for an Organization
create - Create an API Credential
get - Get an API Credential
update - Update an API Credential
delete - Delete an API Credential

Cloud.Workspaces

list - List all Workspaces for the specified Organization
create - Create a Workspace in the specified Organization
get - Get a Workspace
update - Update a Workspace
delete - Delete a Workspace

Cloud.Billing.Credits.ContractsUtilization

list - Get contract credit utilization

Cloud.Billing.Credits.Timeseries

list - Get credits timeseries

Cloud.Billing.Credits.Stats

list - Get credit balance and consumption

Cloud.Billing.Credits.Grants

list - Get credit grants

Auth

Auth.Tokens

get - Log in and fetch an authentication token

Collectors

list - List all Collectors
create - Create a Collector
get - Get a Collector
update - Update a Collector
delete - Delete a Collector

DatabaseConnections

list - List all Database Connections
create - Create a Database Connection
get - Get a Database Connection
update - Update a Database Connection
delete - Delete a Database Connection

Datasets

list - List all Lake Datasets (Cribl.Cloud only)
create - Create a Lake Dataset (Cribl.Cloud only)
get - Get a Lake Dataset (Cribl.Cloud only)
update - Update a Lake Dataset (Cribl.Cloud only)
delete - Delete a Lake Dataset (Cribl.Cloud only)

Destinations

list - List all Destinations
create - Create a Destination
get - Get a Destination
update - Update a Destination
delete - Delete a Destination

Destinations.Pq

get - Get persistent queue info for a Destination
clear - Clear the persistent queue for a Destination

Destinations.Samples

get - Get sample event data for a Destination
create - Send sample event data to a Destination

Destinations.Statuses

list - List the status of all Destinations
get - Get the status of a Destination

Functions

list - List all Functions
get - Get a Function

Groups

list - List all Worker Groups, Outpost Groups, or Edge Fleets
create - Create a Worker Group, Outpost Group, or Edge Fleet
get - Get a Worker Group, Outpost Group, or Edge Fleet
update - Update a Worker Group, Outpost Group, or Edge Fleet
delete - Delete a Worker Group, Outpost Group, or Edge Fleet
deploy - Deploy commits to a Worker Group, Outpost Group, or Edge Fleet

Groups.Acl

get - Get the Access Control List for a Worker Group

Groups.Acl.Teams

get - Get the Access Control List for teams with permissions on a Worker Group

Groups.Configs.Versions

get - Get the configuration version for a Worker Group

Health

get - Get the health status of the server

Nodes

list - Get detailed metadata for Worker, Edge, or Outpost Nodes
get - Get detailed metadata for a Node
restart - Restart Worker, Edge, or Outpost Nodes
count - Get a count of Worker, Edge, or Outpost Nodes

Nodes.Summaries

get - Get a summary of the deployment for a Cribl product

Packs

list - List all Packs
install - Install a Pack
upload - Upload a Pack file
get - Get a Pack
upgrade - Upgrade a Pack
uninstall - Uninstall a Pack

Pipelines

list - List all Pipelines
create - Create a Pipeline
get - Get a Pipeline
update - Update a Pipeline
delete - Delete a Pipeline

Routes

list - List all Routes
get - Get a Routing table
update - Update a Routing table
append - Add a Route to the end of the Routing table

Sources

list - List all Sources
create - Create a Source
get - Get a Source
update - Update a Source
delete - Delete a Source

Sources.HecTokens

create - Add an HEC token to a Splunk HEC Source
update - Update metadata for an HEC token

Sources.Pq

get - Get persistent queue info for a Source
clear - Clear the persistent queue for a Source

Sources.Statuses

list - List the status of all Sources
get - Get the status of a Source

System

System.Captures

create - Capture live data (NDJSON stream)

System.Settings

restart - Restart the Cribl server

System.Settings.Cribl

list - Get system settings
update - Update system settings

Versioning

Versions.Branches

list - List all branches in the Git repository
get - Get the active Git branch name

Versions.Commits

list - List the commit history
create - Create a new commit for pending changes
diff - Get the diff for a commit
push - Push local commits to the remote repository
revert - Revert a commit in the local repository
get - Get the diff and log message for a commit
undo - Discard uncommitted (staged) changes

Versions.Commits.Files

count - Get a count of files changed since a commit
list - Get names and statuses of files changed since a commit

Versions.Configs

get - Get Git integration configuration and status

Versions.Statuses

get - Get the status of the current working tree

Metadata

Release files for cribl-python-sdk 0.0.1a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cribl-python-sdk 0.0.1a1
File	Size	Uploaded
cribl_python_sdk-0.0.1a1.tar.gz	262.4 kB	Oct 19, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cribl-python-sdk 0.0.1a1
File	Interpreter	ABI	Platform	Reset
cribl_python_sdk-0.0.1a1-py3-none-any.whl 280.0 kB Oct 19, 2026	Python 3	none	any	Details

Total release size: 542.4 kB

Release files / cribl_python_sdk-0.0.1a1.tar.gz

Download URL	cribl_python_sdk-0.0.1a1.tar.gz
Size	262.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`ddb3851f5a2d38c9dfbfea24976f777965c78fe535e9e687f3e374c20d8ee831`
BLAKE2b-256 checksum How to use checksums	`40d30e546f1cb3aa2af3cf406242c98b50a3e4ceae6bfbc42ba5c41ab02c4a72`
Upload date	Oct 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/criblio/cribl-python-sdk
Publishing commit: github.com/criblio/cribl-python-sdk/tree/03685f0efc0979229c1adf7ac33485a7656078cb

Workflow

Publishing configuration: github.com/criblio/cribl-python-sdk/blob/03685f0efc0979229c1adf7ac33485a7656078cb/.github/workflows/publish.yml
Publishing logs: github.com/criblio/cribl-python-sdk/actions/runs/39250267757/attempts/1

Artifact

Subject: cribl_python_sdk-0.0.1a1.tar.gz
SHA-256 checksum: ddb3851f5a2d38c9dfbfea24976f777965c78fe535e9e687f3e374c20d8ee831 Verifying attestations

Release files / cribl_python_sdk-0.0.1a1-py3-none-any.whl

Download URL	cribl_python_sdk-0.0.1a1-py3-none-any.whl
Size	280.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6a20ac0755173bebfb04050db6344c9a7a6f4d54ee7eabf470c59c1d9631e560`
BLAKE2b-256 checksum How to use checksums	`e5b534ec482a0f37869f14ae8c0f32967b69db106f5dcf8b00b98f9c0223c109`
Upload date	Oct 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`