splunkctl 0.11.2__tar.gz → 0.12.0__tar.gz

{splunkctl-0.11.2 → splunkctl-0.12.0}/MANIFEST.in

@@ -3,3 +3,4 @@ prune docs
 prune samples
 prune scripts
 prune installers
+graft docs/guides

{splunkctl-0.11.2/splunkctl.egg-info → splunkctl-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunkctl
-Version: 0.11.2
+Version: 0.12.0
 Summary: Open-source MCP server and CLI for Splunk Enterprise SIEM and Splunk SOAR.
 Author: dannyota
 License-Expression: Apache-2.0
@@ -27,7 +27,7 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: tabulate>=0.9
 Requires-Dist: requests>=2.32
 Requires-Dist: defusedxml>=0.7
-Requires-Dist: mcp<2,>=1.28.1
+Requires-Dist: mcp<3,>=2
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"

splunkctl-0.12.0/docs/guides/alerts.md

@@ -0,0 +1,79 @@
+# 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
+maintenance, you need to suppress noisy rules before they flood the
+on-call channel. After the fact, auditors ask which alerts fired and
+which were suppressed. These commands cover all three workflows.
+
+## Commands
+
+```bash
+splunkctl alerts list                         # list fired alerts
+splunkctl alerts get 'Alert Name'             # details for one alert group
+splunkctl alerts actions                      # list alert action types
+splunkctl alerts suppress 'Alert Name' \
+    --duration 7200 --yes                     # suppress for 2 hours
+```
+
+## Triage during an incident
+
+List all currently fired alerts to see what the environment is telling you.
+Output includes name, trigger count, triggered time, and severity.
+
+```bash
+splunkctl alerts list
+splunkctl alerts get 'Brute Force Login Attempts'
+```
+
+## Check alert action types
+
+See which action types (email, webhook, script, etc.) are configured on
+the instance. Useful before creating or modifying saved searches that
+fire alerts.
+
+```bash
+splunkctl alerts actions
+```
+
+## Suppress during a maintenance window
+
+Suppression is guarded -- dry-run by default. The first command below
+previews the change; the second applies it. Duration is in seconds.
+
+```bash
+splunkctl alerts suppress 'Brute Force Login Attempts' --duration 7200
+splunkctl alerts suppress 'Brute Force Login Attempts' --duration 7200 --yes
+```
+
+Suppress multiple alerts in a loop during a planned outage:
+
+```bash
+for rule in 'Brute Force Login Attempts' 'Failed VPN Auth' 'DNS Exfil'; do
+  splunkctl alerts suppress "$rule" --duration 14400 --yes
+done
+```
+
+## JSON output for scripts and agents
+
+Pass `--json` to get structured output suitable for piping into `jq`,
+feeding into an LLM agent, or storing as audit evidence.
+
+```bash
+splunkctl alerts list --json                          # all fired alerts
+splunkctl alerts list --json | jq '.[] | select(.severity >= 6)'
+splunkctl alerts get 'Brute Force Login Attempts' --json > alert_detail.json
+```
+
+An LLM agent can consume the JSON directly to decide next steps --
+for example, correlating fired alerts with a change window calendar
+or auto-filing tickets for high-severity triggers.
+
+## Options
+
+| Flag | Applies to | Description |
+|------|-----------|-------------|
+| `--duration` | `suppress` | Suppression length in seconds (default 3600) |
+| `--json` | all | Force JSON output regardless of TTY |
+| `--format` | all | Output format: `table`, `json`, `csv`, `jsonl` |
+| `--yes` | `suppress` | Apply the mutation (skip dry-run preview) |

splunkctl-0.12.0/docs/guides/apps.md

@@ -0,0 +1,65 @@
+# Apps
+
+Splunk's detection and enrichment capabilities live in apps --
+Technology Add-ons (TAs) for data normalization, security content packs
+like Splunk Enterprise Security, and custom apps with org-specific
+detections. Managing these remotely lets you deploy, update, and audit
+apps across instances without SSH or manual Web UI clicks.
+
+## Commands
+
+```bash
+splunkctl apps list                           # list installed apps
+splunkctl apps get SplunkForwarder            # get app details
+splunkctl apps install --path ./app.spl --yes # install from local file
+splunkctl apps install --path ./app.tar.gz \
+    --force --yes                             # force overwrite
+splunkctl apps uninstall my_app --yes         # uninstall
+splunkctl apps update my_app --enabled \
+    --visible --yes                           # enable + show
+splunkctl apps update my_app --disabled \
+    --hidden --yes                            # disable + hide
+splunkctl apps reload --yes                   # reload all apps
+```
+
+## Remote install
+
+`apps install --path` uploads a local `.spl` or `.tar.gz` package to
+the remote Splunk instance via the Web UI handler. No SSH, no SCP, no
+server filesystem access needed -- push from your laptop to any
+reachable instance.
+
+Use `--force` to overwrite an existing app of the same name.
+
+## Practical examples
+
+```bash
+# Deploy a TA for Windows event log normalization
+splunkctl apps install \
+    --path ./Splunk_TA_windows-8.9.0.spl --yes
+
+# Upgrade a security content pack (force overwrite)
+splunkctl apps install \
+    --path ./DA-ESS-ContentUpdate-4.29.0.spl --force --yes
+
+# Disable an app during an incident (stop its scheduled searches)
+splunkctl apps update SplunkEnterpriseSecuritySuite \
+    --disabled --yes
+
+# Re-enable after the incident
+splunkctl apps update SplunkEnterpriseSecuritySuite \
+    --enabled --yes
+
+# Audit installed apps -- pipe JSON to jq for scripting
+splunkctl apps list --json | jq '.[] | {name, version, disabled}'
+
+# Reload all app configs after a bulk change
+splunkctl apps reload --yes
+```
+
+## Notes
+
+- App install may require a Splunk restart to activate new modular
+  inputs or scripted lookups. The CLI does not restart automatically.
+- `--force` is required when reinstalling or upgrading an app that
+  already exists on the instance.

splunkctl-0.12.0/docs/guides/audit.md

@@ -0,0 +1,125 @@
+# Change audit & RBAC attestation
+
+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.
+
+## Why this matters
+
+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
+normalizes both into one schema and joins the RBAC graph so neither
+requires bespoke SPL per engagement.
+
+## Commands
+
+```bash
+splunkctl audit changes                                   # last 24h, up to 500
+splunkctl audit changes --since -7d --until -1d            # explicit window
+splunkctl audit changes --user jdoe                        # exact-match user
+splunkctl audit changes --action edit                      # substring-match action
+splunkctl audit changes --object-type saved_search          # exact-match object type
+splunkctl audit changes --limit 2000 --json                # raise the display cap
+
+splunkctl audit rbac                                        # one row per user
+splunkctl audit rbac --format csv --out recert-2026-07.csv  # recertification export
+splunkctl audit rbac --roles-only                            # one row per role
+```
+
+## `audit changes`: normalized schema
+
+Every row has exactly six keys, in this order: `time`, `user`, `action`,
+`object`, `object_type`, `app`. Splunk's `_audit` index mixes two
+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 |
+| `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
+regardless of shape and gives one consistent, sortable value.
+
+There is no literal `data.object`/`data.object_type` key on real
+`audittrailv2` events; `data.name`/`data.type` are the nearest
+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
+aren't changes to a named object.
+
+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` —
+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 —
+reaches the SPL string. Verified live with `--debug`:
+
+```bash
+$ splunkctl --debug audit changes --user 'x" | delete' --action 'y | outputlookup evil.csv'
+...
+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
+`--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.
+`--user`/`--object-type` are case-insensitive exact match; `--action` is case-insensitive substring match.
+
+## `audit rbac`: aggregation
+
+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
+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
+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
+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
+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.
+
+## Options
+
+| Flag | Applies to | Description |
+|------|-----------|--------------|
+| `--since` | `changes` | Earliest time (default `-24h`) |
+| `--until` | `changes` | Latest time (default `now`) |
+| `--user` | `changes` | Filter by user, case-insensitive exact match |
+| `--action` | `changes` | Filter by action, case-insensitive substring match |
+| `--object-type` | `changes` | Filter by object type, case-insensitive exact match |
+| `--limit` | `changes` | Max results after client-side filtering (default 500) |
+| `--roles-only` | `rbac` | One row per role instead of per user |
+
+## Implementation notes
+
+`changes` runs over the existing oneshot-search infrastructure
+(`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
+search involved.

splunkctl-0.12.0/docs/guides/conf.md

@@ -0,0 +1,84 @@
+# Conf
+
+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`.
+
+## Why this matters
+
+Detections depend on more than saved searches: macros expand reusable
+SPL fragments, eventtypes classify events, tags drive CIM compliance,
+and calculated fields live in `props.conf` alongside sourcetypes.
+`parsers` only reaches `props.conf`/`transforms.conf`; `conf` reaches
+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`,
+`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
+anything, so review the preview before applying to a sensitive file.
+
+## Commands
+
+```bash
+splunkctl conf files                          # list conf files
+splunkctl conf list macros                    # list stanzas in macros.conf
+splunkctl conf list macros --app my_app       # scope to one app's stanzas
+splunkctl conf get macros my_macro            # full stanza config
+splunkctl conf get macros my_macro --key definition  # one key
+splunkctl conf set macros my_macro \
+    definition='index=main' --yes             # create/update keys
+splunkctl conf unset macros my_macro definition --yes  # clear a key
+splunkctl conf reload macros --yes            # reload the conf file
+```
+
+## Recipes
+
+### Add a macro
+
+Create a macro and verify it before rollout:
+
+```bash
+splunkctl conf set macros my_macro \
+    definition='index=main sourcetype=syslog' --yes
+splunkctl conf get macros my_macro
+```
+
+### Audit an eventtype
+
+```bash
+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,
+new value on the right, `add` for a brand-new key:
+
+```bash
+splunkctl conf set macros my_macro definition='index=main'
+# [DRY RUN] ...
+#   definition: index=old -> index=main
+```
+
+### List conf files to find the right one
+
+```bash
+splunkctl conf files --filter tag
+```
+
+## Tips
+
+- `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
+  remove a stanza, use the dedicated command group for that conf file
+  when one exists (e.g. `parsers delete` for `props.conf`).
+- `--app` on `conf list`/`conf files` matters: the unscoped default
+  view can miss app-private stanzas, same as `rules list`/`dashboards
+  list`.
+- Reload the conf file after a `set`/`unset` if the change needs to
+  take effect immediately (`conf reload <file> --yes`).

splunkctl-0.12.0/docs/guides/configure.md

@@ -0,0 +1,120 @@
+# Configure
+
+## Interactive setup
+
+```bash
+splunkctl config init
+```
+
+Prompts for host, port, auth method (token or username/password), tests the
+connection, and writes `~/.splunkctl/config.yaml` with `0600` permissions.
+
+## Config file
+
+Location: `~/.splunkctl/config.yaml`
+
+```yaml
+host: "localhost"
+port: 8089
+scheme: "https"
+username: "admin"
+password: ""            # optional, can use token instead
+token: ""               # bearer token (preferred)
+verify: true            # TLS cert verification (default: on)
+app: "search"           # default app context
+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
+during setup (default: yes).
+
+## Profiles (dev/UAT/prod)
+
+For more than one Splunk instance, add a `profiles:` map and a `current:`
+pointer instead of the flat keys above:
+
+```yaml
+profiles:
+  dev:
+    host: "dev.splunk.internal"
+    username: "admin"
+    password: "devpass"
+  uat:
+    host: "uat.splunk.internal"
+    token: "..."
+  prod:
+    host: "prod.splunk.internal"
+    token: "..."
+current: "uat"           # active profile when nothing else selects one
+```
+
+```bash
+splunkctl config init --profile uat ...   # create/update one named profile
+splunkctl config use uat                  # point 'current' at it (no connectivity test)
+splunkctl config show                     # active profile (redacted) + other names
+splunkctl config show --profile prod      # show a specific profile without switching
+splunkctl --profile prod rules list       # override for a single invocation
+```
+
+**Selection precedence**: `--profile <name>` global flag > `current:`
+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
+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
+file). The first time you run `config init --profile <name>` against a
+legacy file, it's upgraded to the `profiles:` schema in place: the old flat
+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
+between dev/UAT/prod never happens silently. The banner is built from local
+config only; it never opens a connection.
+
+## Environment variables
+
+| Variable | Maps to |
+|---|---|
+| `SPLUNK_HOST` | `host` |
+| `SPLUNK_PORT` | `port` |
+| `SPLUNK_TOKEN` | `token` |
+| `SPLUNK_USER` | `username` |
+| `SPLUNK_PASS` | `password` |
+
+Env vars override fields of whichever profile is selected — same as they
+override the flat config today.
+
+## Resolution priority
+
+1. CLI flags (`--host`, `--port`, `--token`)
+2. Environment variables
+3. Profile (config file)
+
+## Watch mode
+
+Re-run any read-only command at a fixed interval, clearing the screen
+between runs (like `watch(1)` on Linux). Errors are printed in place and
+the loop continues. Press Ctrl-C to stop.
+
+```bash
+splunkctl --watch 5 indexes list        # refresh every 5 seconds
+splunkctl --watch 10 server health      # poll server health
+splunkctl --watch 3 rules list --filter brute   # filtered view
+```
+
+Requires an interactive terminal (TTY). Mutation commands (those guarded
+by `--yes`) are rejected.
+
+## Verify
+
+```bash
+splunkctl config show    # display config (secrets redacted)
+splunkctl config test    # test connectivity + auth
+```

splunkctl-0.12.0/docs/guides/dashboards.md

@@ -0,0 +1,17 @@
+# Dashboards
+
+## Commands
+
+```bash
+splunkctl dashboards list                 # list dashboards
+splunkctl dashboards list --app search    # filter by app
+splunkctl dashboards get <name>           # get definition (XML)
+splunkctl dashboards create --name new_dash --file dash.xml \
+    --app search --yes
+splunkctl dashboards update <name> --file updated.xml \
+    --app search --yes
+splunkctl dashboards delete <name> --app search --yes
+splunkctl dashboards export <name> --out dash.xml
+```
+
+Uses the `Dashboard`/`Dashboards` entity classes from the SDK fork.

splunkctl-0.12.0/docs/guides/datamodels.md

@@ -0,0 +1,164 @@
+# Data models (CIM/tstats acceleration)
+
+Mature SOC detections run on accelerated CIM data models via `| tstats`
+— this group answers "which models exist," "is acceleration healthy,"
+and "trigger a rebuild when stale." No SDK entity for data models
+(unlike dashboards/lookups/HEC tokens) — every command is a thin, typed
+wrapper around the raw `datamodel/model` and `admin/summarization` REST
+collections, same pattern as `kvstore`/`server`.
+
+## Why two REST resources
+
+`datamodel/model`'s `content["acceleration"]` field is only the
+**configuration** — `enabled`, `earliest_time` (the summarization
+window), `cron_schedule`. It does **not** carry build progress. Percent
+complete, the actual summarized earliest/latest range, size, and the
+last build error live on a separate `admin/summarization` entity, one
+per accelerated model, named `tstats:DM_<app>_<model>`.
+
+This shape was confirmed against this project's own Splunk 10.4 install,
+not guessed from REST trial and error alone: the installed
+`splunk.models.summarization.Summarization` REST model class
+(`$SPLUNK_HOME/lib/python3.13/site-packages/splunk/models/summarization.py`)
+declares every `summary.*` field this group reads, and the bundled Data
+Model Manager JS (`data_model_manager.js`) builds the exact
+`tstats:DM_<app>_<model>` id when it fetches a model's acceleration
+info in the Splunk Web UI. Both ship with splunkd itself, so they
+describe exactly what this REST API version does — the same UI page an
+admin would open to check acceleration health.
+
+## Commands
+
+```bash
+splunkctl datamodels list                              # name, app, accelerated, disabled
+splunkctl datamodels list --app Splunk_SA_CIM
+splunkctl datamodels list --filter auth
+
+splunkctl datamodels get Authentication                 # detection-engineering summary
+splunkctl datamodels get Authentication --definition    # raw objects/fields/calculations JSON
+splunkctl datamodels get Authentication --app Splunk_SA_CIM
+
+splunkctl datamodels acceleration                       # every accelerated model's build status
+splunkctl datamodels acceleration Authentication         # one model (accelerated or not)
+
+splunkctl datamodels rebuild Authentication --yes        # re-summarize from scratch (guarded)
+```
+
+## `list`: cheap collection fields only
+
+Columns: `name`, `app`, `accelerated` (bool), `disabled` (bool) — all
+read straight off the collection listing, no per-model follow-up call.
+`--app` (default: all apps), plus the uniform `--limit`/`--offset`/
+`--filter` paging (F2): `--filter` forces a full fetch with client-side
+case-insensitive name matching; without it, `--limit`/`--offset` pass
+straight through to the REST call as `count`/`offset`.
+
+## `get`: detection-engineering summary, not the full blob
+
+A data model's raw definition (`content["description"]`) is a
+JSON-encoded string that can run past 250KB for a CIM model with dozens
+of objects — `get` parses it once and surfaces only what a detection
+engineer actually needs:
+
+- `name`, `app`, `displayName`, `disabled`
+- `acceleration_enabled`, `acceleration_earliest_time`,
+  `acceleration_cron_schedule` — the acceleration *config* (not status;
+  use `acceleration` for that)
+- `object_count`, `objects` (comma-joined object names)
+- `root_search` — the base object's first constraint search, i.e. what
+  raw index/sourcetype/tag the whole model actually covers
+
+Pass `--definition` to get the raw, pretty-printed objects/fields/
+calculations JSON instead — same shape as `dashboards get --definition`,
+just for a data model's object hierarchy instead of a Studio dashboard's
+visualization JSON.
+
+## `acceleration`: the money command
+
+`datamodels acceleration` (no argument) lists every model whose
+acceleration config is enabled, with its build status:
+
+- `enabled` — acceleration config state (should always be `true` here)
+- `has_summary` — whether `admin/summarization` has an entity yet (a
+  freshly-enabled model with a cron that hasn't fired yet is
+  `enabled: true, has_summary: false` — accelerated, but nothing built)
+- `is_complete` / `percent_complete` — from `summary.complete` (a 0–1
+  fraction server-side; rendered here as a 0–100 percentage, rounded to
+  1 decimal place: `round(float(complete) * 100, 1)`)
+- `size`, `earliest_summarized`, `latest_summarized` — raw
+  `summary.size`/`summary.earliest_time`/`summary.latest_time`,
+  unmodified (epoch seconds, not reformatted)
+- `last_error` — `summary.last_error` (a list server-side, one entry
+  per distributed peer) joined with `; `; empty string when clean
+
+If nothing is accelerated, this cleanly renders an empty result — never
+an error — and skips the `admin/summarization` fetch entirely (no
+accelerated models means nothing to look up).
+
+`datamodels acceleration <name>` shows one model regardless of whether
+it's accelerated: `enabled: false` (with every other field blank/`null`)
+is a valid, non-error answer to "is this model accelerated at all" — an
+agent auditing acceleration coverage across many models shouldn't have
+to special-case the read path for the ones that aren't accelerated yet.
+Only a model that doesn't exist at all is an error (`kind: "not_found"`).
+
+## `rebuild`: guarded, disable-then-re-enable
+
+There is no dedicated "rebuild" REST verb for data model acceleration.
+Splunk Web's own "Rebuild" button (confirmed from the installed Data
+Model Manager JS) works by POSTing `datamodel/model/<name>` twice:
+first `acceleration=0` (disable), then `acceleration=1` with the same
+`acceleration.earliest_time` re-sent explicitly (re-enable) — this drops
+the existing tsidx summary and re-summarizes historical data for the
+same window from scratch. `datamodels rebuild <name>` does exactly this,
+behind the standard dry-run guard:
+
+```bash
+splunkctl datamodels rebuild Authentication            # [DRY RUN] preview, no changes
+splunkctl datamodels rebuild Authentication --yes       # applies: disable, then re-enable
+```
+
+The dry-run preview names the model, its app, the preserved
+`earliest_time` window, and states plainly that this re-summarizes
+historical data from scratch — there is no partial/incremental rebuild.
+
+**Only meaningful for an already-accelerated model.** If the named
+model's acceleration config is disabled, `rebuild` exits 1 with a clear
+message *before* the dry-run/`--yes` guard even runs — passing `--yes`
+against a non-accelerated model does not print a preview and does not
+touch anything, it just fails the same way the bare dry-run would.
+
+**Known caveat (inherent to the underlying REST API, not this CLI):**
+because a rebuild is two separate POSTs, a failure between them (e.g. a
+permission or connectivity error on the second call) can leave the
+model disabled without the summary having restarted. This is exactly
+the same risk Splunk Web's own Rebuild button carries — there is no
+atomic rebuild operation to fall back to. A rebuild failure surfaces
+through the normal F1 classified envelope; re-running `datamodels get
+<name>` afterward shows whether acceleration ended up enabled again.
+
+## Errors
+
+REST failures are never caught locally — they flow straight through the
+CLI's F1 error-envelope classification (`splunkctl.errors.classify`), so
+a down or misconfigured instance always surfaces a clean `kind`/
+`http_status`/`message`, never blank output or a raw traceback:
+
+```bash
+$ splunkctl --json datamodels list
+{"error": {"kind": "http", "http_status": 503, "message": "..."}}
+```
+
+## Live-verified status
+
+`list`/`get`/`acceleration` (read paths) and `rebuild`'s dry-run preview
+and not-accelerated rejection are live-verified against the local dev
+instance. The instance ships Splunk Security Essentials (sample content
+and CIM-aware detections) but not the `Splunk_SA_CIM` add-on itself, so
+no data model on it is actually accelerated — `acceleration`'s populated
+build-status row (non-zero percent complete, a real summarized range)
+and `rebuild --yes`'s two-POST apply path are unit-tested against the
+REST shape above (verified via the installed Splunk source, not
+guessed) rather than live-verified end-to-end; live verification of a
+populated, real acceleration build is pending an instance with an
+actually-accelerated CIM model.