splunkctl

Operate Splunk Enterprise as code — for SOC teams, detection engineers, and AI agents.

Docs · Catalog · Releases

---

A Python CLI that queries, inspects, and manages a remote Splunk Enterprise instance over the REST API. Built on the splunk-sdk-python fork with Click. The core loop is pull live state → review the diff → push it back — one state engine covering rules, parsers, macros, lookups, and dashboards, with a change-evidence report artifact for bank change tickets. It's built for humans and LLM agents alike: deterministic flags, --json everywhere, structured error envelopes, and an embedded agent operating guide (splunkctl skill).

Every mutation is dry-run by default. Nothing changes until you pass --yes. Always preview, read it, then apply.

What it does

• Config as code — state pull → edit → state diff → state push across rules, parsers, macros, lookups, and dashboards (diff-only). Push writes a before→after JSON report artifact usable as change-ticket evidence. Push never deletes.
• Detection engineering — rules CRUD + YAML import/export, macros, eventtypes, tags, data model acceleration health, lookup definitions + automatic lookups (transforms.conf/props.conf wiring), and first-class --email-to/--webhook-url alert-action flags.
• ES incident review — es notables list/get/update for the SOC triage loop (status, owner, urgency, disposition, comment via notable_update); feature-detected on Enterprise Security.
• Compliance & audit — audit changes normalizes both _audit event shapes into one schema; audit rbac produces a users × roles × capabilities attestation view for access recertification.
• KV store — collection + document CRUD, JSONL import/export with 500-doc batch chunking, query with server-side filtering.
• Topology health — server cluster/shcluster/deployment reads distinguish "no threat" from "an indexer is down" in clustered deployments.
• Agent reliability — structured JSON error envelope with typed taxonomy (auth/permission/not_found/timeout/...), uniform --limit/--offset/--filter on every list surface, multi-instance profiles with a bank-safety guard banner ((profile: uat @ host:port)).
• Built for agents — splunkctl commands --json for self-discovery, splunkctl skill / skill install for LLM agent harnesses, guard markers on every mutation, dual output (TTY = table, pipe = JSON).

Install

pip install splunkctl
pip install git+https://github.com/dannyota/splunk-sdk-python@splunkctl

Requires Python 3.13+. The second line installs the forked SDK which adds dashboard, lookup, and HEC token entity classes. Without it, core commands (search, rules, alerts, indexes, inputs, apps, users) still work.

Development

git clone https://github.com/dannyota/splunkctl
cd splunkctl
pip install -e '.[dev]'
splunkctl --version

Quickstart

splunkctl config init                         # interactive setup
splunkctl doctor                              # check connection, auth, permissions
splunkctl search run 'index=main | head 10'   # run a search
splunkctl rules list                          # list detection rules
splunkctl commands --json                     # discover every verb

CLI usage

# Read
splunkctl rules list --app Splunk_Security_Essentials --json
splunkctl alerts list --json
splunkctl datamodels acceleration
splunkctl audit rbac --format csv --out rbac.csv

# Mutate (dry-run first, --yes to apply)
splunkctl rules disable 'My Rule'             # preview
splunkctl rules disable 'My Rule' --yes       # apply
splunkctl es notables update <id> --status closed --owner analyst --yes

# Config-as-code
splunkctl state pull --dir config/            # snapshot live state
splunkctl state diff --dir config/            # structured drift report
splunkctl state push --dir config/ --report r.json --yes  # deploy + evidence

Commands

Group	Description
doctor	Connection, auth, health, and permissions check
config	Setup, profiles (dev/UAT/prod), test connectivity
info	Server info (version, OS, license)
search	Run, export, oneshot, upload, job management
rules	Detection rules — CRUD, import/export (YAML), alert-action flags
alerts	Fired alerts, alert actions, suppression
dashboards	Dashboard CRUD (XML/JSON)
indexes	Index management
inputs	Data inputs (monitor, tcp, udp, script, http)
lookups	Lookup tables, definitions, automatic lookups
hec	HEC token management
parsers	Source types, field extractions, import/export
apps	App install (.spl/.tar.gz), uninstall, update
users	User and role management
server	Messages, license, KV store, cluster/SHC/deployment health
es	ES notable-event triage (feature-detected)
audit	Change audit + RBAC attestation
kvstore	KV store collection + document CRUD
conf	Generic conf file/stanza editor (any .conf)
macros	Search macros — list, get, set
eventtypes	Event types — list, get
tags	Tags — list, get
datamodels	Data model definitions + acceleration health
state	Config-as-code pull/diff/push with change-evidence reports
commands	Machine-readable command tree (JSON)
skill	Embedded agent operating guide

Global flags

--json              Force JSON output
--format FMT        Output format: table, json, csv, jsonl
--fields f1,f2      Project specific fields
--out FILE          Write output to file
--yes / -y          Apply mutations (skip dry-run preview)
--timeout N         Request timeout in seconds (default 30)
--config FILE       Config file path
--profile NAME      Named profile (dev/UAT/prod)
--debug             HTTP request/response logging

Dry-run by default

All write operations preview what would change. Pass --yes to apply. Every preview and confirmation includes the target profile and host so an agent never mistakes UAT for prod.

splunkctl rules delete 'My Rule'
# [DRY RUN] Delete saved search 'My Rule' (profile: uat @ uat.splunk.internal:8089)
# Pass --yes to apply.

splunkctl rules delete 'My Rule' --yes
# Applying: Delete saved search 'My Rule' (profile: uat @ uat.splunk.internal:8089)
# Deleted saved search 'My Rule'.

Structured errors

Under --json or piped output, errors emit a single-line JSON envelope on stderr with a typed kind for programmatic branching:

{"error": {"kind": "not_found", "http_status": 404, "message": "..."}}

Kinds: auth, permission, not_found, conflict, http, connection, timeout, error (fallback).

SDK fork

splunkctl depends on a fork of splunk-sdk-python that adds entity classes missing from the upstream SDK:

Entity	Service property	Purpose
Dashboard	service.dashboards	Dashboard CRUD
LookupTableFile	service.lookup_table_files	Lookup table metadata + download
HECToken	service.hec_tokens	HEC token management

pip install git+https://github.com/dannyota/splunk-sdk-python@splunkctl

Agent integration

splunkctl ships with an embedded operating guide for AI agents (Claude Code, etc.):

splunkctl skill                    # print the guide
splunkctl skill install            # install to ~/.claude/skills/
splunkctl commands --json          # JSON command tree for discovery

The guide covers auth, every command with examples, ES recipes, SPL patterns, the mutation guard, error handling, and workflow recipes.

License

Apache-2.0