splunkctl 0.10.0__tar.gz → 0.11.0__tar.gz

{splunkctl-0.10.0 → splunkctl-0.11.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: splunkctl
-Version: 0.10.0
-Summary: CLI tool for Splunk Enterprise SIEM operations.
+Version: 0.11.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: Repository, https://github.com/dannyota/splunkctl
 Project-URL: Issues, https://github.com/dannyota/splunkctl/issues
-Keywords: splunk,siem,security,cli,detection,spl
+Keywords: splunk,mcp,model-context-protocol,siem,soar,security,cli,detection,spl
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: System Administrators
@@ -109,7 +109,7 @@ ingest. Built for humans and LLM agents alike: deterministic flags,
   creates SOAR containers + typed CEF artifacts using the official CIM-to-CEF
   field map, with SDI dedup, severity mapping, and last-artifact automation
   batching.
-- **Built for agents** — built-in MCP server with 237 auto-generated tools,
+- **Built for agents** — built-in MCP server with 259 auto-generated tools,
   progressive discovery (5 meta-tools + focus/unfocus), 33 guide resources,
   guard markers on every mutation, dual output (TTY = table, pipe = JSON).
 
@@ -267,7 +267,7 @@ splunkctl mcp install              # register in .mcp.json
 splunkctl mcp serve                # start stdio MCP server
 ```
 
-The MCP server auto-generates 229 typed tools from the Click command tree
+The MCP server auto-generates 259 typed tools from the Click command tree
 (SIEM + SOAR) with progressive discovery -- agents start with 5 meta-tools
 (`help`, `usage`, `focus`, `unfocus`, `run`) and dynamically load typed
 schemas per command group. Subgroup-granular focus works for nested groups

{splunkctl-0.10.0 → splunkctl-0.11.0}/README.md

@@ -71,7 +71,7 @@ ingest. Built for humans and LLM agents alike: deterministic flags,
   creates SOAR containers + typed CEF artifacts using the official CIM-to-CEF
   field map, with SDI dedup, severity mapping, and last-artifact automation
   batching.
-- **Built for agents** — built-in MCP server with 237 auto-generated tools,
+- **Built for agents** — built-in MCP server with 259 auto-generated tools,
   progressive discovery (5 meta-tools + focus/unfocus), 33 guide resources,
   guard markers on every mutation, dual output (TTY = table, pipe = JSON).
 
@@ -229,7 +229,7 @@ splunkctl mcp install              # register in .mcp.json
 splunkctl mcp serve                # start stdio MCP server
 ```
 
-The MCP server auto-generates 229 typed tools from the Click command tree
+The MCP server auto-generates 259 typed tools from the Click command tree
 (SIEM + SOAR) with progressive discovery -- agents start with 5 meta-tools
 (`help`, `usage`, `focus`, `unfocus`, `run`) and dynamically load typed
 schemas per command group. Subgroup-granular focus works for nested groups

{splunkctl-0.10.0 → splunkctl-0.11.0}/pyproject.toml

@@ -5,13 +5,13 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "splunkctl"
 dynamic = ["version"]
-description = "CLI tool for Splunk Enterprise SIEM operations."
+description = "Open-source MCP server and CLI for Splunk Enterprise SIEM and Splunk SOAR."
 readme = "README.md"
 requires-python = ">=3.13"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 authors = [{ name = "dannyota" }]
-keywords = ["splunk", "siem", "security", "cli", "detection", "spl"]
+keywords = ["splunk", "mcp", "model-context-protocol", "siem", "soar", "security", "cli", "detection", "spl"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Environment :: Console",
@@ -51,8 +51,10 @@ Homepage = "https://github.com/dannyota/splunkctl"
 Repository = "https://github.com/dannyota/splunkctl"
 Issues = "https://github.com/dannyota/splunkctl/issues"
 
-[tool.setuptools]
-packages = ["splunkctl", "splunkctl.commands", "splunkctl.mcp", "splunkctl.soar"]
+# Auto-discover subpackages — a hardcoded list silently dropped
+# splunkctl.commands.soar from every wheel (v0.7.0–v0.10.0).
+[tool.setuptools.packages.find]
+include = ["splunkctl*"]
 
 [tool.setuptools.dynamic]
 version = { attr = "splunkctl.__version__" }

{splunkctl-0.10.0 → splunkctl-0.11.0}/splunkctl/__init__.py

@@ -1,3 +1,3 @@
 """CLI tool for Splunk Enterprise and Splunk SOAR operations."""
 
-__version__ = "0.10.0"
+__version__ = "0.11.0"

{splunkctl-0.10.0 → splunkctl-0.11.0}/splunkctl/client.py

@@ -18,6 +18,20 @@ import splunklib.client as splunk_client
 import urllib3
 
 from splunkctl import config as cfg_mod
+from splunkctl.errors import WebSessionError
+
+_tls_warned: bool = False
+
+
+def _warn_tls_off() -> None:
+    """Print one warning per process when TLS verification is disabled."""
+    global _tls_warned  # noqa: PLW0603
+    if not _tls_warned:
+        _tls_warned = True
+        click.echo(
+            "Warning: TLS certificate verification is disabled for this connection.",
+            err=True,
+        )
 
 
 class SplunkClient:
@@ -98,6 +112,7 @@ class SplunkClient:
 
             if not cfg.get("verify", False):
                 connect_args["verify"] = False
+                _warn_tls_off()
 
             if self._timeout:
                 connect_args["timeout"] = self._timeout
@@ -174,9 +189,10 @@ class _WebSession:
         self._username: str = service.username
         self._password: str = service.password
         if not self._username or not self._password:
-            raise RuntimeError(
+            raise WebSessionError(
                 "Lookup upload requires username/password authentication. "
-                "Token-only auth cannot authenticate to Splunk Web UI."
+                "Token-only auth cannot authenticate to Splunk Web UI.",
+                kind="auth",
             )
 
         web_conf = service.confs["web"]["settings"]
@@ -225,19 +241,22 @@ class _WebSession:
         try:
             body: dict[str, Any] = resp.json()
         except ValueError:
-            raise RuntimeError(
-                f"Splunk Web login failed: HTTP {resp.status_code}"
+            raise WebSessionError(
+                f"Splunk Web login failed: HTTP {resp.status_code}",
+                kind="auth",
             ) from None
         if body.get("status") == "fail":
             msg = body.get("msg", "unknown error")
-            raise RuntimeError(f"Splunk Web login failed: {msg}")
+            raise WebSessionError(f"Splunk Web login failed: {msg}", kind="auth")
 
         for cookie in self._session.cookies:
             if cookie.name and cookie.name.startswith("splunkweb_csrf_token"):
                 self._csrf_token = cookie.value
                 break
         if not self._csrf_token:
-            raise RuntimeError("Could not obtain CSRF token from Splunk Web")
+            raise WebSessionError(
+                "Could not obtain CSRF token from Splunk Web", kind="web"
+            )
         self._logged_in = True
 
     def upload_lookup(
@@ -315,7 +334,9 @@ class _WebSession:
             },
         )
         if resp.status_code >= 400:
-            raise RuntimeError(f"App install failed: HTTP {resp.status_code}")
+            raise WebSessionError(
+                f"App install failed: HTTP {resp.status_code}", kind="web"
+            )
 
 
 def _expect_ok(resp: requests.Response, what: str) -> None:
@@ -323,12 +344,15 @@ def _expect_ok(resp: requests.Response, what: str) -> None:
     try:
         result: dict[str, Any] = resp.json()
     except ValueError:
-        raise RuntimeError(
+        raise WebSessionError(
             f"{what} failed: HTTP {resp.status_code} — "
-            f"unexpected response: {resp.text[:200]!r}"
+            f"unexpected response: {resp.text[:200]!r}",
+            kind="web",
         ) from None
     if result.get("status") != "OK":
-        raise RuntimeError(f"{what} failed: {result.get('msg', 'unknown error')}")
+        raise WebSessionError(
+            f"{what} failed: {result.get('msg', 'unknown error')}", kind="web"
+        )
 
 
 def rest_get_json(

{splunkctl-0.10.0 → splunkctl-0.11.0}/splunkctl/commands/commands_meta.py

@@ -39,6 +39,8 @@ def _walk(group: click.Group) -> list[dict[str, Any]]:
     """Recursively build the command tree."""
     nodes: list[dict[str, Any]] = []
     for name, cmd in sorted(group.commands.items()):
+        if cmd.hidden:
+            continue
         node: dict[str, Any] = {
             "name": name,
             "help": (cmd.help or "").split("\n")[0],

{splunkctl-0.10.0 → splunkctl-0.11.0}/splunkctl/commands/common.py

@@ -1,5 +1,8 @@
 """Shared helpers for command groups."""
 
+import subprocess
+import sys
+import time
 from collections.abc import Callable, Iterable
 from typing import Any
 
@@ -18,6 +21,29 @@ def spl_quote(value: str) -> str:
     return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
 
 
+class UnsafeLookupNameError(click.ClickException):
+    """Lookup name contains characters unsafe for SPL interpolation."""
+
+
+def spl_quote_lookup_name(name: str) -> str:
+    """Quote a lookup name for safe interpolation into SPL commands.
+
+    Used in ``| inputlookup <name>`` to prevent SPL injection. Rejects
+    names containing newlines or NUL (which could break out of quoting
+    regardless of escaping), escapes backslashes and double quotes, and
+    wraps the result in double quotes.
+
+    Raises:
+        UnsafeLookupNameError: If the name contains newlines or NUL.
+    """
+    if "\n" in name or "\r" in name or "\x00" in name:
+        raise UnsafeLookupNameError(
+            f"Lookup name {name!r} contains newline or NUL characters "
+            "and cannot be safely used in SPL."
+        )
+    return '"' + name.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
 _ALERT_TYPES = (
     "custom",
     "number of events",
@@ -354,6 +380,54 @@ _REQUIRED_ACTION_FIELDS: dict[str, str] = {
 }
 
 
+def resolve_leaf_command(
+    group: click.Group,
+    args: list[str],
+) -> click.Command | None:
+    """Walk the Click tree to find the leaf command for the given args."""
+    cmd: click.Command = group
+    for tok in args:
+        if tok.startswith("-"):
+            continue
+        if isinstance(cmd, click.Group) and tok in cmd.commands:
+            cmd = cmd.commands[tok]
+        else:
+            break
+    return cmd if cmd is not group else None
+
+
+def watch_loop(
+    ctx: click.Context,
+    interval: int,
+    invoke_fn: Callable[[click.Context], Any],
+) -> None:
+    """Re-invoke a read-only command every *interval* seconds.
+
+    Clears the terminal between runs (like ``watch(1)``). Errors are
+    printed in-place and the loop continues. Ctrl-C (KeyboardInterrupt)
+    exits cleanly with code 0.
+
+    Args:
+        ctx: The top-level Click context.
+        interval: Seconds between runs.
+        invoke_fn: Callable that re-invokes the resolved command tree.
+    """
+    while True:
+        if sys.stdout.isatty():
+            # Hardcoded command, no user input — safe to invoke directly.
+            subprocess.run(  # noqa: S603, S607
+                ["cls" if sys.platform == "win32" else "clear"],
+                check=False,
+            )
+        try:
+            invoke_fn(ctx)
+        except SystemExit:
+            pass
+        except Exception as exc:  # noqa: BLE001
+            output.error(str(exc))
+        time.sleep(interval)
+
+
 def app_scope(app: str | None) -> dict[str, str]:
     """Build the ``app``/``owner`` kwargs for an app-scoped list call.
 

{splunkctl-0.10.0 → splunkctl-0.11.0}/splunkctl/commands/config_cmd.py

@@ -93,7 +93,8 @@ def init(
         else click.prompt("Password", default="", hide_input=True)
     )
     scheme = scheme or "https"
-    verify = verify if verify is not None else False
+    if verify is None:
+        verify = click.confirm("Verify TLS certificates", default=True)
 
     cfg: dict[str, Any] = {
         "host": host,

{splunkctl-0.10.0 → splunkctl-0.11.0}/splunkctl/commands/dashboards.py

@@ -176,7 +176,7 @@ def get_dashboard(
     client = get_client(ctx)
     try:
         d = _resolve(client.service, name, app)
-    except (KeyError, Exception):
+    except KeyError:
         output.error(f"Dashboard '{name}' not found.", kind="not_found")
         ctx.exit(1)
         return
@@ -303,7 +303,7 @@ def update_dashboard(
     client = get_client(ctx)
     try:
         d = _resolve(client.service, name, app)
-    except (KeyError, Exception):
+    except KeyError:
         output.error(f"Dashboard '{name}' not found.", kind="not_found")
         ctx.exit(1)
         return
@@ -332,8 +332,8 @@ def delete_dashboard(ctx: click.Context, name: str, *, app: str) -> None:
     client = get_client(ctx)
     try:
         d = _resolve(client.service, name, app)
-    except (KeyError, Exception) as exc:
-        output.error(f"Delete failed: {exc}")
+    except KeyError:
+        output.error(f"Dashboard '{name}' not found.", kind="not_found")
         ctx.exit(1)
         return
     d.delete()
@@ -390,7 +390,7 @@ def export_dashboard(
     client = get_client(ctx)
     try:
         d = _resolve(client.service, name, app)
-    except (KeyError, Exception):
+    except KeyError:
         output.error(f"Dashboard '{name}' not found.", kind="not_found")
         ctx.exit(1)
         return
@@ -470,7 +470,7 @@ def share_dashboard(
     client = get_client(ctx)
     try:
         d = _resolve(client.service, name, app)
-    except (KeyError, Exception):
+    except KeyError:
         output.error(f"Dashboard '{name}' not found.", kind="not_found")
         ctx.exit(1)
         return

splunkctl-0.11.0/splunkctl/commands/docs_cmd.py

@@ -0,0 +1,324 @@
+"""`splunkctl docs generate` — the generated command reference.
+
+Walks the same runnable-command tree as `commands` and writes one markdown
+page per top-level group into docs/commands/ plus an index, and syncs the
+marker-delimited block in docs/_sidebar.md — so the docs-site reference can
+never drift from the CLI. Hidden: a maintainer/CI tool, not an operator
+surface. `--check` regenerates in memory and fails when the committed files
+are stale (the CI freshness gate).
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import click
+
+from splunkctl.guard import is_guarded
+
+_START = "<!-- commands:start -->"
+_END = "<!-- commands:end -->"
+_NOTICE = "<!-- Generated by `splunkctl docs generate` — do not edit by hand. -->"
+
+
+@click.group("docs", hidden=True)
+def docs_group() -> None:
+    """Generate documentation and command-reference pages (maintainers)."""
+
+
+@dataclass
+class _Entry:
+    """One runnable command with its full path (e.g. ``soar playbooks list``)."""
+
+    path: str
+    cmd: click.Command
+
+
+@dataclass
+class _Group:
+    """One reference page: a top-level command group and its runnable commands.
+
+    Single leaf top-level commands (doctor, info, ...) are folded into the
+    synthetic "global" group.
+    """
+
+    name: str
+    short: str
+    entries: list[_Entry]
+
+
+def _first_line(text: str | None) -> str:
+    return (text or "").split("\n")[0].strip()
+
+
+def _walk(group: click.Group, prefix: str, out: list[_Entry]) -> None:
+    """Collect every visible runnable command under ``group``."""
+    for name, cmd in sorted(group.commands.items()):
+        if cmd.hidden:
+            continue
+        path = f"{prefix} {name}".strip()
+        if isinstance(cmd, click.Group):
+            _walk(cmd, path, out)
+        else:
+            out.append(_Entry(path, cmd))
+
+
+def _collect_groups(root: click.Group) -> list[_Group]:
+    """Bucket every runnable command by its top-level segment.
+
+    A top-level command with no subcommands lands in "global"; groups are
+    sorted by name with "global" last.
+    """
+    entries: list[_Entry] = []
+    _walk(root, "", entries)
+
+    shorts = {name: _first_line(cmd.help) for name, cmd in root.commands.items()}
+
+    by_top: dict[str, list[_Entry]] = {}
+    for e in entries:
+        top = e.path.split(" ")[0]
+        by_top.setdefault(top, []).append(e)
+
+    groups: list[_Group] = []
+    global_entries: list[_Entry] = []
+    for top, es in sorted(by_top.items()):
+        # A single entry whose path IS the top-level name is a plain leaf
+        # command (doctor, info, commands, ...) — folded into "global".
+        if len(es) == 1 and es[0].path == top:
+            global_entries.append(es[0])
+            continue
+        groups.append(_Group(top, shorts.get(top, ""), es))
+    if global_entries:
+        groups.append(_Group("global", "Top-level commands", global_entries))
+    return groups
+
+
+def _cell(s: str) -> str:
+    """Make a string safe inside a one-line markdown table cell."""
+    return " ".join(s.replace("|", "\\|").split())
+
+
+def _usage(e: _Entry) -> str:
+    ctx = click.Context(e.cmd, info_name=f"splunkctl {e.path}")
+    pieces = e.cmd.collect_usage_pieces(ctx)
+    return " ".join([f"splunkctl {e.path}", *pieces])
+
+
+def _long_help(e: _Entry) -> str:
+    r"""Body of the command help below the summary line, ``\b`` markers dropped."""
+    lines = (e.cmd.help or "").split("\n")[1:]
+    return "\n".join(ln for ln in lines if ln.strip() != "\b").strip()
+
+
+def _flag_default(p: click.Option) -> str:
+    d = p.default
+    if isinstance(d, bool):
+        return "true" if d else "false"
+    # Only scalar defaults are meaningful in docs — sentinels, tuples, and
+    # callables render as "-".
+    if isinstance(d, (str, int, float)) and d != "":
+        return str(d)
+    return "-"
+
+
+def _flag_type(p: click.Option) -> str:
+    if isinstance(p.type, click.Choice):
+        return "choice: " + ", ".join(str(c) for c in p.type.choices)
+    if p.is_flag:
+        return "flag"
+    return p.type.name
+
+
+def _flag_rows(cmd: click.Command) -> list[str]:
+    """Render the command's options as markdown table rows."""
+    rows: list[str] = []
+    for p in cmd.params:
+        if not isinstance(p, click.Option) or p.hidden or p.name == "help":
+            continue
+        shorts = [o for o in p.opts if not o.startswith("--")]
+        longs = [o for o in p.opts if o.startswith("--")]
+        name = ", ".join(shorts + longs)
+        if p.secondary_opts:
+            name += " / " + ", ".join(p.secondary_opts)
+        desc = p.help or ""
+        if p.required:
+            desc = f"{desc} [required]".strip()
+        rows.append(
+            f"| `{_cell(name)}` | {_cell(_flag_type(p))}"
+            f" | {_cell(_flag_default(p))} | {_cell(desc)} |"
+        )
+    return rows
+
+
+def _render_entry(e: _Entry) -> list[str]:
+    out = [f"## {e.path}", ""]
+    if short := _first_line(e.cmd.help):
+        out += [short, ""]
+    if is_guarded(e.cmd):
+        out += ["> Guarded mutation — dry-run by default; apply with `--yes`.", ""]
+    out += ["```text", _usage(e), "```"]
+
+    # The long help is CLI help text, not authored markdown — fence it
+    # verbatim so stray tables/lists/pipes inside it can never break the page.
+    if long := _long_help(e):
+        fence = "~~~~" if "```" in long else "```"
+        out += ["", f"{fence}text", long, fence]
+
+    if rows := _flag_rows(e.cmd):
+        out += [
+            "",
+            "**Flags**",
+            "",
+            "| Flag | Type | Default | Description |",
+            "|---|---|---|---|",
+            *rows,
+        ]
+    return out
+
+
+def _render_group(g: _Group) -> str:
+    title = "Global commands" if g.name == "global" else f"splunkctl {g.name}"
+    lines = [_NOTICE, "", f"# {title}", ""]
+    if g.short:
+        lines.append(g.short)
+    for e in g.entries:
+        lines += ["", *_render_entry(e)]
+    return "\n".join(lines) + "\n"
+
+
+def _render_index(groups: list[_Group]) -> str:
+    lines = [
+        _NOTICE,
+        "",
+        "# Command reference",
+        "",
+        "Generated from the Click command tree — run `splunkctl docs generate`",
+        'after changing a command. "Guarded" commands are live mutations behind',
+        "the standard dry-run/`--yes` gate; everything else is a read.",
+        "",
+        "| Group | Commands | Description |",
+        "|---|---|---|",
+    ]
+    for g in groups:
+        lines.append(
+            f"| [{g.name}]({g.name}.md) | {len(g.entries)} | {_cell(g.short)} |"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def _render_pages(groups: list[_Group]) -> dict[str, str]:
+    """Render every group page plus the index, keyed by filename."""
+    pages = {f"{g.name}.md": _render_group(g) for g in groups}
+    pages["README.md"] = _render_index(groups)
+    return pages
+
+
+def _sidebar_block(pages: dict[str, str]) -> str:
+    names = sorted(n.removesuffix(".md") for n in pages if n != "README.md")
+    lines = [_START, "- **Command reference**", "  - [Overview](commands/README.md)"]
+    lines += [f"  - [{n}](commands/{n}.md)" for n in names]
+    lines.append(_END)
+    return "\n".join(lines)
+
+
+def _patch_sidebar(content: str, block: str) -> str:
+    """Replace the marker-delimited sidebar block, or insert before Design."""
+    if (start := content.find(_START)) >= 0:
+        end = content.find(_END)
+        if end < start:
+            raise click.ClickException(
+                f"sidebar: {_START} found without a following {_END}"
+            )
+        return content[:start] + block + content[end + len(_END) :]
+    anchor = "- **Design**"
+    if (i := content.find(anchor)) >= 0:
+        return content[:i] + block + "\n\n" + content[i:]
+    return content.rstrip("\n") + "\n\n" + block + "\n"
+
+
+def _stale_pages(pages: dict[str, str], out_dir: Path) -> list[str]:
+    """Committed *.md files the current command tree no longer generates."""
+    if not out_dir.is_dir():
+        return []
+    return sorted(
+        f.name
+        for f in out_dir.iterdir()
+        if f.is_file() and f.name.endswith(".md") and f.name not in pages
+    )
+
+
+def _write_docs(pages: dict[str, str], out_dir: Path, sidebar: str) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for name, content in pages.items():
+        (out_dir / name).write_text(content, encoding="utf-8")
+    stale = _stale_pages(pages, out_dir)
+    for name in stale:
+        (out_dir / name).unlink()
+    if sidebar:
+        path = Path(sidebar)
+        raw = path.read_text(encoding="utf-8")
+        path.write_text(_patch_sidebar(raw, _sidebar_block(pages)), encoding="utf-8")
+    msg = f"generated {len(pages)} page(s) in {out_dir}"
+    if stale:
+        msg += f", removed {len(stale)} stale"
+    click.echo(msg)
+
+
+def _check_docs(pages: dict[str, str], out_dir: Path, sidebar: str) -> list[str]:
+    problems: list[str] = []
+    for name, content in pages.items():
+        f = out_dir / name
+        if not f.is_file():
+            problems.append(f"missing: {name}")
+        elif f.read_text(encoding="utf-8") != content:
+            problems.append(f"stale: {name}")
+    problems += [f"orphaned: {name}" for name in _stale_pages(pages, out_dir)]
+    if sidebar:
+        raw = Path(sidebar).read_text(encoding="utf-8")
+        if _patch_sidebar(raw, _sidebar_block(pages)) != raw:
+            problems.append(f"stale: {sidebar} command-reference block")
+    return sorted(problems)
+
+
+@docs_group.command("generate")
+@click.option(
+    "--out",
+    "out_dir",
+    default="docs/commands",
+    help="Output directory for the generated pages.",
+)
+@click.option(
+    "--sidebar",
+    default="docs/_sidebar.md",
+    help="Sidebar file to sync (empty to skip).",
+)
+@click.option(
+    "--check",
+    is_flag=True,
+    help="Verify the committed pages are current; write nothing.",
+)
+@click.pass_context
+def docs_generate(ctx: click.Context, out_dir: str, sidebar: str, check: bool) -> None:
+    """Generate the per-group command-reference pages under docs/commands/.
+
+    Walk the command tree and write one markdown page per top-level command
+    group into docs/commands/ (plus an index README), and sync the
+    commands:start/end block in docs/_sidebar.md. With --check, nothing is
+    written: the run fails when any committed page, the index, or the
+    sidebar block is stale — the CI freshness gate.
+    """
+    root = ctx.find_root().command
+    if not isinstance(root, click.Group):
+        raise click.ClickException("Cannot resolve CLI root.")
+    pages = _render_pages(_collect_groups(root))
+    if check:
+        if problems := _check_docs(pages, Path(out_dir), sidebar):
+            click.echo(
+                "command reference is out of date — run `splunkctl docs generate`:",
+                err=True,
+            )
+            for p in problems:
+                click.echo(f"  {p}", err=True)
+            ctx.exit(1)
+        click.echo("ok: command reference is current")
+        return
+    _write_docs(pages, Path(out_dir), sidebar)