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 a built-in MCP server (splunkctl mcp serve) with progressive tool discovery.

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 — built-in MCP server with 129 auto-generated tools, progressive discovery (5 meta-tools + focus/unfocus), 22 guide resources, 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

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:

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

Agent integration (MCP)

splunkctl ships with a built-in MCP server for AI agent integration:

splunkctl mcp install              # register in .mcp.json
splunkctl mcp serve                # start stdio MCP server

The MCP server auto-generates 129 typed tools from the Click command tree with progressive discovery — agents start with 5 meta-tools (help, usage, focus, unfocus, run) and dynamically load typed schemas per command group. 22 guide resources are served as guide:// URIs. Mutations are guarded: yes=true to apply (dry-run by default).

License

Apache-2.0