splunkctl 0.12.0__tar.gz → 0.14.0__tar.gz

splunkctl-0.14.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: splunkctl
+Version: 0.14.0
+Summary: Open-source MCP server and CLI for Splunk Enterprise SIEM and Splunk SOAR.
+Author: dannyota
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/dannyota/splunkctl
+Project-URL: Documentation, https://splunkctl.danny.vn
+Project-URL: Repository, https://github.com/dannyota/splunkctl
+Project-URL: Issues, https://github.com/dannyota/splunkctl/issues
+Project-URL: Changelog, https://github.com/dannyota/splunkctl/blob/master/CHANGELOG.md
+Keywords: splunk,mcp,model-context-protocol,siem,soar,security,cli,detection,spl
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: splunk-sdk>=2.0
+Requires-Dist: click>=8.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tabulate>=0.9
+Requires-Dist: requests>=2.32
+Requires-Dist: defusedxml>=0.7
+Requires-Dist: mcp<3,>=2.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-tabulate; extra == "dev"
+Requires-Dist: types-defusedxml; extra == "dev"
+Provides-Extra: browser
+Requires-Dist: playwright>=1.45; extra == "browser"
+Dynamic: license-file
+
+# splunkctl
+
+<a href="https://splunkctl.danny.vn"><img src="https://raw.githubusercontent.com/dannyota/splunkctl/master/docs/assets/banner.svg" alt="splunkctl: CLI and MCP server for Splunk Enterprise, Enterprise Security, and SOAR" width="600"></a>
+
+Operate Splunk Enterprise, Enterprise Security, and Splunk SOAR from a terminal, or give an AI agent the same commands through MCP.
+
+Requires Python 3.13+ and credentials for your Splunk instance.
+
+## Quickstart
+
+```bash
+python -m pip install splunkctl
+splunkctl config init
+splunkctl doctor
+```
+
+[Documentation](https://splunkctl.danny.vn) · [Installation requirements](https://splunkctl.danny.vn/#/guides/install)
+
+## Tasks
+
+- Investigate: run SPL, read fired alerts, and triage Enterprise Security notables. [Search](https://splunkctl.danny.vn/#/guides/search), [Triage notables](https://splunkctl.danny.vn/#/guides/es)
+- Deploy detections: export saved searches to YAML, review the diff, and import them on another instance. [Manage detection rules](https://splunkctl.danny.vn/#/guides/rules)
+- Respond with SOAR: work containers, artifacts, vault files, notes, and playbook runs. [Work SOAR incidents](https://splunkctl.danny.vn/#/guides/soar-incidents)
+- Review configuration drift: pull live state, diff it against version control, and push approved changes with a change report. [Manage configuration as code](https://splunkctl.danny.vn/#/guides/state)
+
+## Safety
+
+Every command that changes a remote Splunk or SOAR instance is guarded. Without `--yes` it prints a preview and exits without changing anything; some previews read the current state first to show a diff. The preview names the target host, and the active profile for Splunk Enterprise, so a change aimed at production is visible before it happens:
+
+```text
+$ splunkctl --profile uat rules delete 'My Rule'
+[DRY RUN] Delete saved search 'My Rule' (profile: uat @ uat.splunk.internal:8089)
+Pass --yes to apply.
+```
+
+Add `--yes` to apply. `splunkctl state push --report FILE` writes a change report with the before and after state for each object, which you can attach to a change ticket.
+
+Local configuration writes are not guarded: `splunkctl config init`, `splunkctl config use`, `splunkctl auth login`, and `splunkctl mcp install` write to your own machine immediately.
+
+## Agent access
+
+The MCP server exposes the command tree to Claude Code, Claude Desktop, Cursor, or any other MCP client. Setup, transports, and the progressive tool-loading model are in the [MCP guide](https://splunkctl.danny.vn/#/guides/mcp).
+
+```bash
+splunkctl mcp install           # register the server in ./.mcp.json
+splunkctl commands --json       # machine-readable command tree
+```
+
+Guarded tools keep the same contract as the CLI: a call previews until the agent passes `yes=true` explicitly.
+
+## Requirements and limitations
+
+- Python 3.13 or newer.
+- A Splunk account with REST API access on port 8089 (or your configured port). Each command needs the Splunk capability or SOAR permission its action requires; `splunkctl doctor` reports which checks pass for the active profile.
+- Enterprise Security commands (`splunkctl es ...`) check for the `SplunkEnterpriseSecuritySuite` app and exit 1 with a `not_found` error when it is not installed.
+- Dashboard, lookup file, and HEC token commands use entity classes from an optional SDK fork. Install it with:
+
+  ```bash
+  python -m pip install git+https://github.com/dannyota/splunk-sdk-python@splunkctl
+  ```
+
+- Browser SAML login needs the `browser` extra: `python -m pip install 'splunkctl[browser]'`.
+
+## Project and support
+
+splunkctl is an independent community project. It is not affiliated with or endorsed by Splunk Inc.
+
+Splunk Inc. publishes an unrelated Go CLI with the same executable name, [`splunk/splunkctl`](https://github.com/splunk/splunkctl). This package also installs `splunkctl-py` and leaves a Splunk-format config file untouched, so both tools can be installed together; see [Relationship to Splunk's splunkctl](https://splunkctl.danny.vn/#/guides/splunk-cli).
+
+- [Releases](https://github.com/dannyota/splunkctl/releases) and [changelog](https://github.com/dannyota/splunkctl/blob/master/CHANGELOG.md)
+- [Issues](https://github.com/dannyota/splunkctl/issues) for bugs and feature requests; see [SECURITY.md](SECURITY.md) for vulnerabilities
+- [CONTRIBUTING.md](CONTRIBUTING.md) for development setup
+- License: [Apache-2.0](https://github.com/dannyota/splunkctl/blob/master/LICENSE)

splunkctl-0.14.0/README.md

@@ -0,0 +1,73 @@
+# splunkctl
+
+<a href="https://splunkctl.danny.vn"><img src="https://raw.githubusercontent.com/dannyota/splunkctl/master/docs/assets/banner.svg" alt="splunkctl: CLI and MCP server for Splunk Enterprise, Enterprise Security, and SOAR" width="600"></a>
+
+Operate Splunk Enterprise, Enterprise Security, and Splunk SOAR from a terminal, or give an AI agent the same commands through MCP.
+
+Requires Python 3.13+ and credentials for your Splunk instance.
+
+## Quickstart
+
+```bash
+python -m pip install splunkctl
+splunkctl config init
+splunkctl doctor
+```
+
+[Documentation](https://splunkctl.danny.vn) · [Installation requirements](https://splunkctl.danny.vn/#/guides/install)
+
+## Tasks
+
+- Investigate: run SPL, read fired alerts, and triage Enterprise Security notables. [Search](https://splunkctl.danny.vn/#/guides/search), [Triage notables](https://splunkctl.danny.vn/#/guides/es)
+- Deploy detections: export saved searches to YAML, review the diff, and import them on another instance. [Manage detection rules](https://splunkctl.danny.vn/#/guides/rules)
+- Respond with SOAR: work containers, artifacts, vault files, notes, and playbook runs. [Work SOAR incidents](https://splunkctl.danny.vn/#/guides/soar-incidents)
+- Review configuration drift: pull live state, diff it against version control, and push approved changes with a change report. [Manage configuration as code](https://splunkctl.danny.vn/#/guides/state)
+
+## Safety
+
+Every command that changes a remote Splunk or SOAR instance is guarded. Without `--yes` it prints a preview and exits without changing anything; some previews read the current state first to show a diff. The preview names the target host, and the active profile for Splunk Enterprise, so a change aimed at production is visible before it happens:
+
+```text
+$ splunkctl --profile uat rules delete 'My Rule'
+[DRY RUN] Delete saved search 'My Rule' (profile: uat @ uat.splunk.internal:8089)
+Pass --yes to apply.
+```
+
+Add `--yes` to apply. `splunkctl state push --report FILE` writes a change report with the before and after state for each object, which you can attach to a change ticket.
+
+Local configuration writes are not guarded: `splunkctl config init`, `splunkctl config use`, `splunkctl auth login`, and `splunkctl mcp install` write to your own machine immediately.
+
+## Agent access
+
+The MCP server exposes the command tree to Claude Code, Claude Desktop, Cursor, or any other MCP client. Setup, transports, and the progressive tool-loading model are in the [MCP guide](https://splunkctl.danny.vn/#/guides/mcp).
+
+```bash
+splunkctl mcp install           # register the server in ./.mcp.json
+splunkctl commands --json       # machine-readable command tree
+```
+
+Guarded tools keep the same contract as the CLI: a call previews until the agent passes `yes=true` explicitly.
+
+## Requirements and limitations
+
+- Python 3.13 or newer.
+- A Splunk account with REST API access on port 8089 (or your configured port). Each command needs the Splunk capability or SOAR permission its action requires; `splunkctl doctor` reports which checks pass for the active profile.
+- Enterprise Security commands (`splunkctl es ...`) check for the `SplunkEnterpriseSecuritySuite` app and exit 1 with a `not_found` error when it is not installed.
+- Dashboard, lookup file, and HEC token commands use entity classes from an optional SDK fork. Install it with:
+
+  ```bash
+  python -m pip install git+https://github.com/dannyota/splunk-sdk-python@splunkctl
+  ```
+
+- Browser SAML login needs the `browser` extra: `python -m pip install 'splunkctl[browser]'`.
+
+## Project and support
+
+splunkctl is an independent community project. It is not affiliated with or endorsed by Splunk Inc.
+
+Splunk Inc. publishes an unrelated Go CLI with the same executable name, [`splunk/splunkctl`](https://github.com/splunk/splunkctl). This package also installs `splunkctl-py` and leaves a Splunk-format config file untouched, so both tools can be installed together; see [Relationship to Splunk's splunkctl](https://splunkctl.danny.vn/#/guides/splunk-cli).
+
+- [Releases](https://github.com/dannyota/splunkctl/releases) and [changelog](https://github.com/dannyota/splunkctl/blob/master/CHANGELOG.md)
+- [Issues](https://github.com/dannyota/splunkctl/issues) for bugs and feature requests; see [SECURITY.md](SECURITY.md) for vulnerabilities
+- [CONTRIBUTING.md](CONTRIBUTING.md) for development setup
+- License: [Apache-2.0](https://github.com/dannyota/splunkctl/blob/master/LICENSE)

{splunkctl-0.12.0 → splunkctl-0.14.0}/docs/guides/alerts.md

@@ -1,4 +1,6 @@
-# Alerts
+<!-- summary: Review fired alerts, inspect alert actions, and manage alert suppression on a Splunk instance from the terminal. -->
+
+# Review fired alerts
 
 Fired alerts are the SOC's incoming work queue. During an incident, you
 need to see what triggered, when, and at what severity. During planned

{splunkctl-0.12.0 → splunkctl-0.14.0}/docs/guides/apps.md

@@ -1,4 +1,6 @@
-# Apps
+<!-- summary: Install, update, reload, and uninstall Splunk apps from local packages with a preview before every change. -->
+
+# Manage apps
 
 Splunk's detection and enrichment capabilities live in apps --
 Technology Add-ons (TAs) for data normalization, security content packs

{splunkctl-0.12.0 → splunkctl-0.14.0}/docs/guides/audit.md

@@ -1,8 +1,10 @@
-# Change audit & RBAC attestation
+<!-- summary: Produce change-audit and role-based access control attestation reports from Splunk for regulators and reviewers. -->
+
+# Audit changes and attest RBAC
 
 Regulator-facing evidence for bank SOC operations: who changed what
 (`audit changes`) and who can do what (`audit rbac`). Both commands are
-**read-only** — no `guard`, no `--yes` needed.
+**read-only**, no `guard`, no `--yes` needed.
 
 ## Why this matters
 
@@ -10,7 +12,7 @@ Banks carry regulator obligations for change-management evidence ("who
 changed this saved search / role / index, and when") and periodic access
 recertification ("who has which capabilities, and why"). Today an agent
 would have to hand-write `index=_audit` SPL and know that Splunk mixes
-**two incompatible event shapes** in that one index — this group
+**two incompatible event shapes** in that one index, this group
 normalizes both into one schema and joins the RBAC graph so neither
 requires bespoke SPL per engagement.
 
@@ -37,11 +39,11 @@ sourcetypes and this command normalizes both:
 
 | Sourcetype | Shape | Mapping |
 |---|---|---|
-| `audittrail` (legacy) | `Audit:[timestamp=..., user=..., action=..., <tail>]` plain text | `user`/`action` parsed directly; `object` only when the line carries a literal `object="..."` marker (common on capability checks like `edit_user`/`edit_roles`); `object_type` is always empty — the legacy format has no per-action type field; `app` from `app="..."` or unquoted `app=...`, when present |
+| `audittrail` (legacy) | `Audit:[timestamp=..., user=..., action=..., <tail>]` plain text | `user`/`action` parsed directly; `object` only when the line carries a literal `object="..."` marker (common on capability checks like `edit_user`/`edit_roles`); `object_type` is always empty, the legacy format has no per-action type field; `app` from `app="..."` or unquoted `app=...`, when present |
 | `audittrailv2` (structured) | one JSON object per line | `user` = `actor.name`; `action` = top-level `action`; `object` = `data.name`; `object_type` = `data.type`; `app` = `data.ownership.app` or `data.attributes.app` |
 
 `time` always comes from Splunk's own indexed `_time` (not a re-parse of
-either embedded timestamp format) — it's present on every event
+either embedded timestamp format), it's present on every event
 regardless of shape and gives one consistent, sortable value.
 
 There is no literal `data.object`/`data.object_type` key on real
@@ -49,20 +51,20 @@ There is no literal `data.object`/`data.object_type` key on real
 equivalents and confirmed present for object/system-category events
 (config changes). Action/authn/check-category events (ad-hoc searches,
 logins, capability grants) carry `data.type` sometimes but rarely
-`data.name` — `object` stays empty for those, which is correct: they
+`data.name`, `object` stays empty for those, which is correct: they
 aren't changes to a named object.
 
-An event matching neither shape is **never dropped** — it comes back as
+An event matching neither shape is **never dropped**, it comes back as
 `action: "unparsed"` with the full raw line in `object`, so evidence
 stays complete even for audit-log formats this parser doesn't yet know.
 
 ## `audit changes`: SPL safety
 
-The dispatched search is always the constant `search index=_audit` —
+The dispatched search is always the constant `search index=_audit`,
 nothing else, ever. `--since`/`--until` go through the oneshot job's
 `earliest_time`/`latest_time` kwargs (not string-composed), and
 `--user`/`--action`/`--object-type` filter the already-normalized rows
-**client-side**, after the fetch. No flag value — however adversarial —
+**client-side**, after the fetch. No flag value, however adversarial,
 reaches the SPL string. Verified live with `--debug`:
 
 ```bash
@@ -72,7 +74,7 @@ POST .../search/v2/jobs/ (body: {'search': 'search index=_audit', ...})
 ```
 
 `--limit` (default 500) applies **after** filtering, not to the raw
-fetch — the raw fetch itself is unbounded (`count=0`) within the
+fetch, the raw fetch itself is unbounded (`count=0`) within the
 `--since`/`--until` window, so a `--user`/`--action` filter never misses
 a match just because it fell outside an arbitrary raw-fetch cutoff.
 A very wide `--since` over a large `_audit` index may fetch all events in that range before limiting, which can be slow; narrow `--since` when possible.
@@ -83,7 +85,7 @@ A very wide `--since` over a large `_audit` index may fetch all events in that r
 One row per user by default: `user`, `email`, `roles` (direct roles,
 semicolon-joined), `capabilities`, `srch_indexes_allowed`. The last two
 are aggregated across the user's direct roles **and the full transitive
-closure of their imported roles** — deduplicated, sorted, and
+closure of their imported roles**, deduplicated, sorted, and
 semicolon-joined. `--roles-only` flips to one row per role instead:
 `role`, `imported_roles` (direct only), `capabilities`,
 `srch_indexes_allowed` (both aggregated the same transitive way, rooted
@@ -91,14 +93,14 @@ at that role).
 
 Example: role `soc_analyst` imports `power`, which imports `user`. A
 `soc_analyst` user's effective `capabilities` is the union of all three
-roles' own capabilities — this is what a role with zero capabilities of
+roles' own capabilities, this is what a role with zero capabilities of
 its own (e.g. Splunk's built-in `splunk-system-role`, which only imports
 `admin`) needs to show its real effective grant, not an empty cell.
 
 ## CSV round-trip safety
 
 Multi-value fields (`roles`, `capabilities`, `srch_indexes_allowed`,
-`imported_roles`) join with `;`, never `\n` — Splunk role/capability/index
+`imported_roles`) join with `;`, never `\n`, Splunk role/capability/index
 names can't contain a semicolon, so this is a safe, lossless join that
 never produces an embedded newline inside a CSV cell. `--format csv`
 output round-trips cleanly through Python's `csv` module.
@@ -121,5 +123,5 @@ output round-trips cleanly through Python's `csv` module.
 (`svc.jobs.oneshot`); the event-shape parsers live in a sibling module,
 `splunkctl/commands/audit_parse.py`, kept separate from the click
 commands since they're pure functions with their own fixture-driven test
-suite. `rbac` is SDK reads only (`svc.roles`, `svc.users`) — no oneshot
+suite. `rbac` is SDK reads only (`svc.roles`, `svc.users`), no oneshot
 search involved.

splunkctl-0.14.0/docs/guides/auth.md

@@ -0,0 +1,63 @@
+<!-- summary: Complete Splunk and SOAR SAML single sign-on, including a second factor, in a browser and reuse the session from every splunkctl command. -->
+
+# Log in through browser SAML
+
+splunkctl can complete Splunk SAML single sign-on (including a second factor)
+in a headed Chromium window and then reuse the resulting product session until
+it expires. The browser handles the identity provider; splunkctl never reads or
+stores TOTP secrets or codes.
+
+## How it works
+
+1. `splunkctl config init --web-url https://splunk.example.com` probes the public login route. When it sees a
+   redirect to an external identity provider, it records `auth_mode: browser`
+   and stores the product `web_url`.
+2. `splunkctl auth login --target <siem|soar>` opens Chromium at the product
+   login route. You complete the IdP prompts, including any TOTP code.
+3. splunkctl extracts only the product session (Splunk `splunkd_<port>` cookie,
+   or SOAR `sessionid` + `csrftoken`) and proves it against the product API.
+4. Normal commands reuse the cached session whenever the active profile selects
+   browser mode. A missing or expired session never opens a browser; the command
+   prints the exact login instruction instead.
+
+## Commands
+
+```text
+splunkctl auth login --target siem
+splunkctl auth login --target soar
+splunkctl auth status [--target siem|soar|both]
+splunkctl auth logout [--target siem|soar|both]
+```
+
+`login` requires exactly one target; two back-to-back browser flows are easy to
+confuse. `status` reports `missing`, `valid`, `expired`, or `unreachable`.
+`logout` always removes the local session, even if the remote endpoint refuses.
+
+## Optional dependency
+
+Browser login needs Playwright and Chromium:
+
+```bash
+pip install 'splunkctl[browser]'
+python -m playwright install chromium
+```
+
+Configuration still succeeds without them. `splunkctl auth login` prints the
+exact commands when they are missing.
+
+## Session storage and security
+
+Sessions are stored under `~/.splunkctl/sessions/<profile>/<target>.json` with
+directory mode `0700` and file mode `0600`. A record holds only the target,
+profile, product origin, product session values, and validation timestamps. It
+never stores passwords, Playwright storage state, identity-provider cookies, or
+TOTP secrets. Session values are redacted from all output.
+
+## What is and is not supported
+
+Supported: SAML browser login for SIEM and SOAR, one target per login, session
+status and logout, automatic SAML detection, and a reusable Keycloak lab.
+
+Not supported in this release: reading or storing TOTP secrets, native Splunk
+Duo or RSA flows, OpenID Connect or OAuth, logging in to both products in one
+command, and a local splunkctl callback redirect.

{splunkctl-0.12.0 → splunkctl-0.14.0}/docs/guides/conf.md

@@ -1,6 +1,8 @@
-# Conf
+<!-- summary: Read and edit any Splunk configuration file and stanza over the REST confs API when no dedicated command group covers it. -->
 
-Generic conf file/stanza editor over the REST `confs` API — the escape
+# Edit any conf file
+
+Generic conf file/stanza editor over the REST `confs` API, the escape
 hatch for any Splunk conf file that doesn't have a dedicated command
 group yet: `macros`, `eventtypes`, `tags`, `limits`, `authorize`,
 `server`, `web`, and everything else under `$SPLUNK_HOME/etc/*/local`.
@@ -14,7 +16,7 @@ and calculated fields live in `props.conf` alongside sourcetypes.
 every other conf file the same way, so nothing detection-relevant is
 locked out of code review or CI.
 
-There is **no blocklist** — `conf` can edit `authorize.conf`,
+There is **no blocklist**, `conf` can edit `authorize.conf`,
 `server.conf`, and `web.conf` just as readily as `macros.conf`. The
 dry-run guard and `--yes` are the only safety net: every `set`/`unset`/
 `reload` preview names the exact file and stanza before it touches
@@ -54,7 +56,7 @@ splunkctl conf get eventtypes authentication --json | jq .
 
 ### Review a stanza change before applying
 
-`conf set` always previews a field-level diff — old value on the left,
+`conf set` always previews a field-level diff, old value on the left,
 new value on the right, `add` for a brand-new key:
 
 ```bash
@@ -71,7 +73,7 @@ splunkctl conf files --filter tag
 
 ## Tips
 
-- `conf set` creates the stanza if it doesn't exist yet — there's no
+- `conf set` creates the stanza if it doesn't exist yet, there's no
   separate create step.
 - The REST API has no true per-key delete; `conf unset` sets keys to
   the empty string (same mechanism `parsers unset` uses). To fully

{splunkctl-0.12.0 → splunkctl-0.14.0}/docs/guides/configure.md

@@ -1,3 +1,5 @@
+<!-- summary: Set up splunkctl profiles for development, UAT, and production, and override them with environment variables or flags. -->
+
 # Configure
 
 ## Interactive setup
@@ -6,8 +8,10 @@
 splunkctl config init
 ```
 
-Prompts for host, port, auth method (token or username/password), tests the
-connection, and writes `~/.splunkctl/config.yaml` with `0600` permissions.
+Prompts for host, port, username, password, and TLS verification, then writes
+`~/.splunkctl/config.yaml` with `0600` permissions. SAML detection runs only
+when `--web-url URL` is supplied. Run `splunkctl config test` to check
+connectivity and authentication after setup.
 
 ## Config file
 
@@ -27,7 +31,7 @@ owner: "nobody"         # default owner context
 
 **TLS verification is on by default.** Production instances with valid
 certificates work out of the box. For lab/dev instances with self-signed
-certs, set `verify: false` explicitly in the profile — `config init` asks
+certs, set `verify: false` explicitly in the profile, `config init` asks
 during setup (default: yes).
 
 ## Profiles (dev/UAT/prod)
@@ -62,8 +66,8 @@ splunkctl --profile prod rules list       # override for a single invocation
 pointer > `default`.
 
 **Legacy files keep working.** A plain flat file (no `profiles:` key) is
-treated as an implicit profile named `default` — nothing to migrate. Bare
-`config init` writes that flat shape — unless the destination file already
+treated as an implicit profile named `default`, nothing to migrate. Bare
+`config init` writes that flat shape, unless the destination file already
 has a `profiles:` key, in which case it folds the new values into
 `profiles.default` instead, leaving sibling profiles and `current`
 untouched (bare `config init` never clobbers an existing multi-profile
@@ -73,8 +77,8 @@ keys move under `profiles.default`, the new named profile is added
 alongside it, and file permissions stay `0600`.
 
 **Guard banner.** Every dry-run preview and `--yes` confirmation prints
-which instance is about to be mutated —
-`[DRY RUN] ... (profile: uat @ uat.splunk.internal:8089)` — so switching
+which instance is about to be mutated,
+`[DRY RUN] ... (profile: uat @ uat.splunk.internal:8089)`, so switching
 between dev/UAT/prod never happens silently. The banner is built from local
 config only; it never opens a connection.
 
@@ -88,14 +92,40 @@ config only; it never opens a connection.
 | `SPLUNK_USER` | `username` |
 | `SPLUNK_PASS` | `password` |
 
-Env vars override fields of whichever profile is selected — same as they
-override the flat config today.
+Environment variables override fields in the selected profile.
 
 ## Resolution priority
 
-1. CLI flags (`--host`, `--port`, `--token`)
-2. Environment variables
-3. Profile (config file)
+1. Environment variables
+2. Selected profile
+3. Built-in defaults
+
+`--profile` and `--config` are the only root options that select configuration.
+
+## Coexistence with Splunk's splunkctl
+
+Splunk's own Go CLI, [`splunk/splunkctl`](https://github.com/splunk/splunkctl),
+also writes `~/.splunkctl/config.yaml`, as a flat file with `host` (a full
+URL) and `token`. This tool never rewrites that file.
+
+- When `~/.splunkctl/config.yaml` is in Splunk's format and no `--config`
+  is given, this tool reads and writes `~/.splunkctl/profiles.yaml`
+  instead and prints one notice on standard error:
+  `Splunk-format config at ~/.splunkctl/config.yaml; using ~/.splunkctl/profiles.yaml`.
+- `splunkctl config init` writes to the same fallback file, so a single
+  `config init` is enough on a host that already has Splunk's tool.
+- An explicit `--config FILE` is never redirected. If that file is in
+  Splunk's format, the command fails with
+  `Splunk-format config at FILE: this is a flat host/token file written by Splunk's splunkctl. Pass a profiles file with --config, or create one with: splunkctl config init --path FILE`
+- `splunkctl doctor` reports the config file in use as its first check.
+- A hand-written file of this tool's own legacy flat format that contains
+  only `host` and `token` is indistinguishable from Splunk's format and is
+  treated the same way. Add `port` or `scheme`, or run `config init`, to
+  keep using it.
+
+Both tools install an executable named `splunkctl`. This package also
+installs `splunkctl-py`, which runs the same CLI, for hosts where Splunk's
+binary comes first on `PATH`.
 
 ## Watch mode
 

splunkctl-0.14.0/docs/guides/dashboards.md

@@ -0,0 +1,108 @@
+<!-- summary: Export Splunk dashboards to files, keep them in version control, and create, update, share, or delete them with a preview before every change. -->
+
+# Manage dashboards
+
+When to use: you want dashboard XML or Studio JSON in version control, need to copy a dashboard between instances, or must change who can see one.
+
+## Prerequisites
+
+- The optional SDK fork, because dashboard commands use its `Dashboard` entity classes:
+
+  ```bash
+  python -m pip install git+https://github.com/dannyota/splunk-sdk-python@splunkctl
+  ```
+
+- A Splunk account with write access to the target app (for example the `admin` or `power` role in `search`).
+
+## Synopsis
+
+```text
+splunkctl dashboards list [--app APP] [--all] [--filter SUBSTRING] [--limit N] [--offset N]
+splunkctl dashboards get <NAME> [--app APP] [--definition]
+splunkctl dashboards export [NAME] [--app APP] [--out FILE] [--definition] [--all --dir DIR]
+splunkctl dashboards create --name <NAME> --file <FILE> [--app APP] [--type classic|studio|auto] [--sharing user|app|global] [--yes]
+splunkctl dashboards update <NAME> --file <FILE> [--app APP] [--type classic|studio|auto] [--yes]
+splunkctl dashboards share <NAME> --sharing <user|app|global> [--owner USER] [--app APP] [--yes]
+splunkctl dashboards delete <NAME> [--app APP] [--yes]
+```
+
+`--app` defaults to `search` for the mutation commands.
+
+## Workflow
+
+### List and inspect
+
+```bash
+splunkctl dashboards list
+splunkctl dashboards list --app search --filter soc
+splunkctl dashboards get soc_overview --app search
+splunkctl dashboards get soc_studio --definition
+```
+
+`list` shows dashboards only; add `--all` to include other views. `--filter`, `--limit`, and `--offset` apply client side after the app and type filters. `get` prints the XML source; `--definition` extracts the Studio JSON and errors on a Classic dashboard.
+
+### Export to files
+
+```bash
+splunkctl dashboards export soc_overview --out dashboards/soc_overview.xml
+splunkctl dashboards export soc_studio --definition --out dashboards/soc_studio.json
+splunkctl dashboards export --all --dir dashboards/
+```
+
+Expected result: one file per dashboard, ready to commit. `--out` overwrites without prompting.
+
+### Create a dashboard from a file
+
+> **Safety:** Target is the Splunk host and app in the active profile (`--app`, default `search`). Impact: a new dashboard appears in that app. Preview with `splunkctl dashboards create --name new_dash --file dash.xml --app search`, apply by adding `--yes`, and verify with `splunkctl dashboards get new_dash --app search`.
+
+```bash
+splunkctl dashboards create --name new_dash --file dash.xml --app search
+splunkctl dashboards create --name new_dash --file dash.xml --app search --yes
+splunkctl dashboards create --name new_dash --file dash.json --type studio --sharing app --yes
+```
+
+`--type auto` (the default) detects Classic XML or Studio JSON from the file.
+
+### Update a dashboard
+
+> **Safety:** Target is the Splunk host and app in the active profile. Impact: the dashboard source is replaced with the file's content. Preview with `splunkctl dashboards update soc_overview --file updated.xml`, apply by adding `--yes`, and verify with `splunkctl dashboards get soc_overview`.
+
+```bash
+splunkctl dashboards update soc_overview --file updated.xml --app search
+splunkctl dashboards update soc_overview --file updated.xml --app search --yes
+```
+
+Export first so you can restore the previous version if needed.
+
+### Change sharing
+
+> **Safety:** Target is the Splunk host and app in the active profile. Impact: who can see the dashboard changes; `global` makes it visible from every app. Preview with `splunkctl dashboards share soc_overview --sharing app`, apply by adding `--yes`, and verify with `splunkctl dashboards list --filter soc_overview --json` (check `sharing`).
+
+```bash
+splunkctl dashboards share soc_overview --sharing app --yes
+splunkctl dashboards share soc_overview --sharing global --owner admin --yes
+```
+
+### Delete a dashboard
+
+> **Safety:** Target is the Splunk host and app in the active profile. Impact: the dashboard is removed and cannot be recovered except from an export. Preview with `splunkctl dashboards delete old_dash --app search`, apply by adding `--yes`, and verify with `splunkctl dashboards list --app search --filter old_dash`.
+
+```bash
+splunkctl dashboards export old_dash --out backup/old_dash.xml
+splunkctl dashboards delete old_dash --app search
+splunkctl dashboards delete old_dash --app search --yes
+```
+
+## Troubleshooting
+
+- `ImportError` or a message about missing `Dashboard` classes: install the SDK fork listed under Prerequisites.
+- `not_found` on `get` or `update`: pass `--app`; the dashboard may live outside `search`.
+- `--definition` errors: the dashboard is Classic XML, not Studio.
+- `permission` on create or share: the account lacks write access to the app, or `global` sharing needs the `admin_all_objects` capability.
+
+## See also
+
+- [Manage configuration as code](state.md), which pulls and diffs dashboards
+- [Run searches](search.md)
+- [Install](install.md)
+- [Command reference: dashboards](../commands/dashboards.md)