splunkctl

Operate Splunk Enterprise and Splunk SOAR as code with a safety-first CLI and MCP server for humans and AI agents.

Documentation · Command catalog · Releases

---

splunkctl is an open-source Python CLI and Model Context Protocol (MCP) server for remote Splunk Enterprise and Splunk SOAR instances. Use it interactively, script its stable JSON output, or give an MCP client access to the same command surface.

• Manage Splunk Enterprise — searches, detection rules, alerts, indexes, inputs, lookups, parsers, dashboards, apps, users, topology, audit, and Enterprise Security workflows.
• Operate Splunk SOAR — containers, artifacts, playbooks, actions, cases, approvals, assets, vault files, custom lists, administration, and SIEM-to-SOAR ingest.
• Keep configuration as code — pull live state, review structured drift, and push approved changes with change-evidence reports.
• Automate safely — mutations preview by default, machine output is structured, errors are typed, and every target profile and host is shown.

Every mutation is a dry run by default. Nothing changes until you pass --yes. Review the target and proposed change before applying it.

Install

python -m pip install splunkctl

Python 3.13 or newer is required. Core commands work with the upstream Splunk SDK installed from PyPI.

Dashboard, lookup-file, and HTTP Event Collector (HEC) token commands use entity classes provided by the optional splunkctl SDK fork:

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

See the installation guide for environment-specific setup.

Quickstart

# Configure and verify Splunk Enterprise
splunkctl config init
splunkctl doctor
# Read live state
splunkctl info
splunkctl search run 'index=main | head 10'
splunkctl rules list --json
# Preview a change; add --yes only after reviewing it
splunkctl rules disable 'My Rule'# Add and verify Splunk SOAR when needed
splunkctl config init --soar
splunkctl soar test
splunkctl soar containers list

Use named profiles for separate development, UAT, and production instances:

splunkctl config init --profile uat
splunkctl --profile uat doctor
splunkctl --profile uat rules list

Core workflows

Configuration as code

The state engine covers rules, parsers, macros, lookups, and selected SOAR objects. Dashboards support pull and diff. Push never deletes remote objects.

splunkctl state pull --dir config/
# Edit the exported files in version control.
splunkctl state diff --dir config/
splunkctl state push --dir config/ --report change-report.json
splunkctl state push --dir config/ --report change-report.json --yes

The report records before-and-after state and whether the change was applied, so it can be attached to a change ticket.

Detection and SIEM operations

splunkctl rules export --path rules.yaml
splunkctl rules import --path rules.yaml
splunkctl datamodels acceleration
splunkctl es notables list --status new --json
splunkctl audit rbac --format csv --out rbac.csv
splunkctl server cluster

Enterprise Security commands detect whether the required app is available and return a clear error when it is not.

Splunk SOAR operations

splunkctl soar containers list --severity high
splunkctl soar playbooks export my_playbook --unpack --out playbooks/
splunkctl soar playbooks run my_playbook --container 42 --wait
splunkctl soar actions run --action geolocate_ip --asset maxmind \
--container 42 --param ip=203.0.113.10 --wait
splunkctl soar ingest --spl 'index=notable' --label events

SOAR commands use the same profiles, dry-run guard, output formats, and error contract as the Splunk Enterprise commands.

MCP for AI agents

splunkctl mcp install
splunkctl mcp serve

The built-in MCP server generates typed tools from the CLI command tree and uses progressive discovery: clients start with a small set of meta-tools, then focus on the command groups needed for the task. Guarded tools require an explicit yes=true before they can mutate a remote instance.

See the MCP guide for stdio and streamable HTTP configuration.

Command groups

Group	Purpose
doctor	Check connection, authentication, health, and permissions
config	Configure profiles and test connectivity
info	Show server version, operating system, and license details
search	Run, export, upload, and manage search jobs
rules	Manage detection rules and YAML import/export
alerts	Inspect fired alerts and manage suppression
dashboards	Manage Classic and Studio dashboards
indexes	Manage indexes
inputs	Manage monitor, TCP, UDP, script, and HTTP inputs
lookups	Manage lookup files, definitions, and automatic wiring
hec	Manage HEC tokens, settings, and events
parsers	Manage source types, props, transforms, and YAML state
apps	Install, update, reload, and uninstall apps
users	Manage users and roles
server	Inspect health, topology, deployment, auth, tokens, and workloads
es	Triage notables and manage correlations and threat intelligence
audit	Review changes and generate role-based access control attestations
kvstore	Manage KV Store collections and documents
conf	Edit any Splunk configuration file and stanza
macros, eventtypes, tags	Manage search knowledge objects
datamodels	Inspect definitions and acceleration health
state	Pull, diff, and push configuration state
soar	Operate Splunk SOAR and run SIEM-to-SOAR workflows
commands	Emit the machine-readable command tree
completion	Generate shell completion for Bash, Zsh, or Fish
mcp	Install and run the MCP server

Run splunkctl COMMAND --help for local help, or use the generated command reference.

Output and safety contracts

Global flags work before or after subcommands:

--json Force JSON output
--format FMT Select table, json, csv, or jsonl
--fields f1,f2 Select output fields
--out FILE Write output to a file
--yes, -y Apply a mutation after previewing it
--timeout N Set the request timeout in seconds
--watch N Repeat a read-only command every N seconds
--config FILE Use a specific configuration file
--profile NAME Select a named profile
--debug Log HTTP requests and responses

Under JSON output, failures emit one JSON object on standard error with a stable error kind:

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

Kinds include auth, permission, not_found, conflict, http, connection, timeout, and error. List commands share uniform filtering and paging flags where the remote API supports them.

Every guarded operation identifies its target before it runs:

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

Development

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

License

Apache-2.0