salt-api-cli 1.3.0__tar.gz → 1.4.1__tar.gz

{salt_api_cli-1.3.0/salt_api_cli.egg-info → salt_api_cli-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: salt-api-cli
-Version: 1.3.0
+Version: 1.4.1
 Summary: CLI to access salt-api
 Author-email: Pradish Bijukchhe <pradish@sandbox.com.np>
 License-Expression: MIT
@@ -33,7 +33,7 @@ Commands come in two layers:
 
 - **Low-level** (`local`, `runner`, `wheel`) map directly to the salt-api
   clients and print **raw JSON**.
-- **High-level** (`state`, `keys`) wrap those clients and render
+- **High-level** (`cmd`, `state`, `keys`) wrap those clients and render
   **readable, colorized output** with `rich`.
 
 ## Installation
@@ -76,9 +76,9 @@ verbatim as indented JSON.
 
 ```
 # Local client — fan out to minions
-salt local '*' test.ping
-salt local 'bml*' cmd.run 'whoami'
-salt local 'bml1' cmd.run 'Get-Date' shell=powershell
+salt local "*" test.ping
+salt local "bml*" cmd.run whoami
+salt local "bml1" cmd.run "Get-Date" shell=powershell
 
 # Runner client (master-side: manage.status, jobs.list_jobs, ...)
 salt runner manage.status
@@ -93,20 +93,27 @@ salt wheel key.list_all
 These wrap the low-level clients and render their output with `rich`.
 
 ```
+# Run a shell command — a live per-minion checklist while it runs, then
+# one block per minion (exit code, stdout, stderr) and an ok/failed summary.
+# Fired async (local_async + cmd.run_all) and polled via the runner, like
+# `state`, so a slow or wide command never holds one long connection open.
+salt cmd "bml*" hostname
+salt cmd "bml1" "Get-Date" shell=powershell
+
 # State runs — a colored table of states, one row each, with a summary.
 # Driven by the local client + state.* functions.
-salt state highstate 'bml1'           # apply the highstate
-salt state test 'bml1'                # dry-run the highstate (forces test=True)
-salt state apply 'bml1' veyon         # apply specific sls module(s)
-salt state apply 'bml1' veyon.ldap test=True
+salt state highstate "bml1"           # apply the highstate
+salt state test "bml1"                # dry-run the highstate (forces test=True)
+salt state apply "bml1" veyon         # apply specific sls module(s)
+salt state apply "bml1" veyon.ldap test=True
 
 # Key management — wraps the wheel client's key.* functions.
 # `keys list` shows one colored panel per status (Accepted/Pending/Denied/Rejected).
 salt keys list
-salt keys accept <id-or-glob>
+salt keys accept "<id-or-glob>"
 salt keys accept-all
-salt keys reject <id-or-glob>
-salt keys delete <id-or-glob>
+salt keys reject "<id-or-glob>"
+salt keys delete "<id-or-glob>"
 ```
 
 Color and panels appear when writing to a terminal; output is plain when

{salt_api_cli-1.3.0 → salt_api_cli-1.4.1}/README.md

@@ -17,7 +17,7 @@ Commands come in two layers:
 
 - **Low-level** (`local`, `runner`, `wheel`) map directly to the salt-api
   clients and print **raw JSON**.
-- **High-level** (`state`, `keys`) wrap those clients and render
+- **High-level** (`cmd`, `state`, `keys`) wrap those clients and render
   **readable, colorized output** with `rich`.
 
 ## Installation
@@ -60,9 +60,9 @@ verbatim as indented JSON.
 
 ```
 # Local client — fan out to minions
-salt local '*' test.ping
-salt local 'bml*' cmd.run 'whoami'
-salt local 'bml1' cmd.run 'Get-Date' shell=powershell
+salt local "*" test.ping
+salt local "bml*" cmd.run whoami
+salt local "bml1" cmd.run "Get-Date" shell=powershell
 
 # Runner client (master-side: manage.status, jobs.list_jobs, ...)
 salt runner manage.status
@@ -77,20 +77,27 @@ salt wheel key.list_all
 These wrap the low-level clients and render their output with `rich`.
 
 ```
+# Run a shell command — a live per-minion checklist while it runs, then
+# one block per minion (exit code, stdout, stderr) and an ok/failed summary.
+# Fired async (local_async + cmd.run_all) and polled via the runner, like
+# `state`, so a slow or wide command never holds one long connection open.
+salt cmd "bml*" hostname
+salt cmd "bml1" "Get-Date" shell=powershell
+
 # State runs — a colored table of states, one row each, with a summary.
 # Driven by the local client + state.* functions.
-salt state highstate 'bml1'           # apply the highstate
-salt state test 'bml1'                # dry-run the highstate (forces test=True)
-salt state apply 'bml1' veyon         # apply specific sls module(s)
-salt state apply 'bml1' veyon.ldap test=True
+salt state highstate "bml1"           # apply the highstate
+salt state test "bml1"                # dry-run the highstate (forces test=True)
+salt state apply "bml1" veyon         # apply specific sls module(s)
+salt state apply "bml1" veyon.ldap test=True
 
 # Key management — wraps the wheel client's key.* functions.
 # `keys list` shows one colored panel per status (Accepted/Pending/Denied/Rejected).
 salt keys list
-salt keys accept <id-or-glob>
+salt keys accept "<id-or-glob>"
 salt keys accept-all
-salt keys reject <id-or-glob>
-salt keys delete <id-or-glob>
+salt keys reject "<id-or-glob>"
+salt keys delete "<id-or-glob>"
 ```
 
 Color and panels appear when writing to a terminal; output is plain when

{salt_api_cli-1.3.0 → salt_api_cli-1.4.1}/salt_api_cli/cli.py

@@ -75,24 +75,37 @@ def _run_keys(cfg: Config, args: argparse.Namespace) -> None:
     highlevel.run_keys(args, wheel)
 
 
+def _run_cmd(cfg: Config, args: argparse.Namespace) -> None:
+    def client(name: str, **kw: Any) -> dict[str, Any]:
+        return call(cfg, name, **kw)
+
+    highlevel.run_cmd(args, client)
+
+
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="salt",
         description="Thin Python CLI for salt-api.",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog=(
+            'quote glob targets with double quotes ("bml*") - they work in\n'
+            "bash, PowerShell, and cmd.exe alike (single quotes are not quotes\n"
+            "in cmd.exe, so 'bml*' there reaches salt with the quotes attached).\n"
+            "\n"
             "low-level (raw JSON):\n"
-            "  salt local '*' test.ping\n"
-            "  salt local 'bml*' cmd.run 'whoami'\n"
-            "  salt local 'bml1' cmd.run 'Get-Date' shell=powershell\n"
+            '  salt local "*" test.ping\n'
+            '  salt local "bml*" cmd.run whoami\n'
+            '  salt local "bml1" cmd.run "Get-Date" shell=powershell\n'
             "  salt runner manage.status\n"
             "  salt wheel key.list_all\n"
             "high-level (readable):\n"
-            "  salt state highstate 'bml1'\n"
-            "  salt state test 'bml1'              # dry-run highstate (test=True)\n"
-            "  salt state apply 'bml1' veyon\n"
+            '  salt cmd "bml*" hostname\n'
+            '  salt cmd "bml1" "Get-Date" shell=powershell\n'
+            '  salt state highstate "bml1"\n'
+            '  salt state test "bml1"              # dry-run highstate (test=True)\n'
+            '  salt state apply "bml1" veyon\n'
             "  salt keys list\n"
-            "  salt keys accept '<id-or-glob>'\n"
+            '  salt keys accept "<id-or-glob>"\n'
             "  salt keys accept-all\n"
         ),
     )
@@ -133,6 +146,15 @@ def _build_parser() -> argparse.ArgumentParser:
     p_wheel.add_argument("function")
     p_wheel.add_argument("args", nargs=argparse.REMAINDER)
 
+    p_cmd = sub.add_parser("cmd", help="run a shell command with readable output")
+    p_cmd.add_argument("target", help="minion target (id or glob)")
+    p_cmd.add_argument("cmdline", metavar="command", help="shell command to run")
+    p_cmd.add_argument(
+        "args",
+        nargs=argparse.REMAINDER,
+        help="key=value args, e.g. shell=powershell",
+    )
+
     p_state = sub.add_parser("state", help="apply states with readable output")
     state_sub = p_state.add_subparsers(dest="action", required=True)
     p_highstate = state_sub.add_parser("highstate", help="apply the highstate")
@@ -192,6 +214,8 @@ def main() -> None:
             _run_client(cfg, "runner", args)
         elif args.command == "wheel":
             _run_client(cfg, "wheel", args)
+        elif args.command == "cmd":
+            _run_cmd(cfg, args)
         elif args.command == "state":
             _run_state(cfg, args)
         elif args.command == "keys":

{salt_api_cli-1.3.0 → salt_api_cli-1.4.1}/salt_api_cli/highlevel.py

@@ -27,6 +27,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import re
 import sys
 import time
 from typing import Any, Callable, cast
@@ -168,12 +169,7 @@ def _print_state_return(minion: str, states: dict[str, Any]) -> None:
     """Render one minion's state run: header, a table of states, summary."""
     ordered = sorted(states.items(), key=lambda kv: kv[1].get("__run_num__", 1 << 30))
 
-    table = Table(box=None, show_header=False, pad_edge=False)
-    table.add_column("marker", no_wrap=True)
-    table.add_column("function", style="cyan", no_wrap=True)
-    table.add_column("ref", style="dim", no_wrap=True)
-    table.add_column("detail", no_wrap=True, overflow="ellipsis")
-
+    rows: list[tuple[Text, str, str, str | Text]] = []
     for key, state in ordered:
         status = _state_status(state)
         marker, style = _STATUS_STYLE[status]
@@ -187,7 +183,28 @@ def _print_state_return(minion: str, states: dict[str, Any]) -> None:
             detail = Text(_short(state.get("comment", ""), 240), style="red")
         else:  # diff / skip
             detail = _short(state.get("comment", ""))
-        table.add_row(Text(marker, style=style), _state_function(key), ref, detail)
+        rows.append((Text(marker, style=style), _state_function(key), ref, detail))
+
+    # Pin the detail column to whatever width is left so rich shrinks *it*
+    # (ellipsis) rather than collapsing the short marker/function/ref columns
+    # to nothing on a narrow terminal. Width budget: 2-space left Padding +
+    # 1-char marker + the natural function/ref widths + three 2-space column
+    # gaps (pad_edge=False). Floor at 20 so detail never vanishes outright.
+    fn_w = max((len(fn) for _, fn, _, _ in rows), default=8)
+    ref_w = max((len(ref) for _, _, ref, _ in rows), default=8)
+    nat_w = max(
+        (len(d.plain if isinstance(d, Text) else d) for _, _, _, d in rows), default=0
+    )
+    detail_w = min(nat_w, max(20, console.width - 2 - 1 - fn_w - ref_w - 3 * 2))
+
+    table = Table(box=None, show_header=False, pad_edge=False)
+    table.add_column("marker", no_wrap=True)
+    table.add_column("function", style="cyan", no_wrap=True)
+    table.add_column("ref", style="dim", no_wrap=True)
+    table.add_column("detail", no_wrap=True, overflow="ellipsis", width=detail_w)
+
+    for row in rows:
+        table.add_row(*row)
 
     counts, total_ms = _count_states(states)
     console.print(Text(minion, style="bold"))
@@ -333,33 +350,42 @@ def _count_cells(counts: dict[str, int]) -> list[Text]:
     ]
 
 
+def _state_cells(val: Any) -> list[Text]:
+    """The five live-view columns for a finished minion's state return: its
+    per-status tally, or a placeholder (plus blanks) for a non-state reply."""
+    if _is_state_return(val):
+        counts, _ = _count_states(cast("dict[str, Any]", val))
+        return _count_cells(counts)
+    return [Text("(no state output)", style="dim"), *[Text("")] * 4]
+
+
 def _live_view(
     targeted: list[str],
     returns: dict[str, Any],
     done: set[str],
     dead: set[str],
     spinner: Spinner,
+    *,
+    n_cells: int,
+    cells_for: Callable[[Any], list[Text]],
 ) -> Group:
-    """A live checklist: a tick for finished minions (with their per-state
-    tally in aligned columns), a spinner for the ones still running, an x for
-    the unreachable, under a one-line status header."""
-    blanks = [Text("")] * 5  # the five count columns, empty
+    """A live checklist: a tick for finished minions (with ``cells_for`` of
+    their reply in aligned columns), a spinner for the ones still running, an x
+    for the unreachable, under a one-line status header. ``n_cells`` is how
+    many trailing columns ``cells_for`` produces (so blank rows stay aligned)."""
+    blanks = [Text("")] * n_cells
     grid = Table.grid(padding=(0, 1))
     grid.add_column(no_wrap=True)  # marker
     grid.add_column(no_wrap=True)  # minion id
-    for _ in range(5):  # ok / changed / would-change / skipped / failed
+    for _ in range(n_cells):  # per-command trailing columns
         grid.add_column(no_wrap=True, justify="left")
     for minion in targeted:
         if minion in dead:
-            grid.add_row(Text("✗", style="red"), Text(minion, style="dim"), *blanks)
+            grid.add_row(Text("X", style="red"), Text(minion, style="dim"), *blanks)
         elif minion in done:
-            val = returns.get(minion)
-            if _is_state_return(val):
-                counts, _ = _count_states(cast("dict[str, Any]", val))
-                cells = _count_cells(counts)
-            else:
-                cells = [Text("(no state output)", style="dim"), *blanks[1:]]
-            grid.add_row(Text("✓", style="green"), Text(minion), *cells)
+            grid.add_row(
+                Text("+", style="green"), Text(minion), *cells_for(returns.get(minion))
+            )
         else:
             grid.add_row(spinner, Text(minion, style="dim"), *blanks)
 
@@ -373,27 +399,41 @@ def _live_view(
     return Group(header, grid)
 
 
-def _stream_state(call: Callable[..., dict[str, Any]], payload: dict[str, Any]) -> None:
-    """Fire a state job async, show a live checklist, then render the results.
-
-    Submits via the ``local_async`` client (returns a job id at once), then
-    polls ``runner jobs.lookup_jid`` until every targeted minion has returned
-    or the deadline trips. While polling it shows a live per-minion checklist
-    (spinner -> tick). Once the run is done the live view is cleared and the
-    coloured per-minion tables print together, followed by a fleet-wide
-    summary. ``call(name, **kw)`` invokes the named salt-api client."""
+def _stream_job(
+    call: Callable[..., dict[str, Any]],
+    payload: dict[str, Any],
+    *,
+    n_cells: int,
+    cells_for: Callable[[Any], list[Text]],
+) -> tuple[dict[str, Any], set[str], set[str], float] | None:
+    """Fire a job async, show a live checklist, and return its raw results.
+
+    Submits ``payload`` via the ``local_async`` client (returns a job id at
+    once), then polls ``runner jobs.lookup_jid`` until every targeted minion
+    has returned or the deadline trips. While polling it shows a live
+    per-minion checklist (spinner -> tick), whose trailing columns come from
+    ``cells_for(value)`` (``n_cells`` of them). Once the run is done the live
+    view is cleared and this returns ``(returns, dead, expected, start)`` for
+    the caller to render — or ``None`` if no job started (already reported).
+    ``call(name, **kw)`` invokes the named salt-api client."""
     submit = call("local_async", **payload)
     info: Any = _first_return(submit)
     jid = info.get("jid")
     if not jid:
-        # No job id: nothing matched, or salt-api answered with an error body.
-        console.print_json(json.dumps(submit))
-        return
+        # No job id: either nothing matched (salt-api hands back an empty
+        # body, e.g. {"return": [{}]}) or it answered with an error body. An
+        # empty info means no minions matched — say so plainly; reserve the
+        # raw JSON dump for an actual error worth showing verbatim.
+        if not info:
+            console.print("(no minions matched the target)")
+        else:
+            console.print_json(json.dumps(submit))
+        return None
 
-    targeted = sorted(info.get("minions") or [])
+    targeted = sorted(info.get("minions") or [], key=_natural_key)
     if not targeted:
         console.print("(no minions matched the target)")
-        return
+        return None
 
     expected = set(targeted)  # shrinks as unreachable minions are dropped
     console.print(f"[dim]job {jid} -> {len(targeted)} minion(s)[/]")
@@ -402,6 +442,12 @@ def _stream_state(call: Callable[..., dict[str, Any]], payload: dict[str, Any])
     dead: set[str] = set()  # probed and confirmed not running the job
     spinner = Spinner("dots", style="cyan")
 
+    def view() -> Group:
+        done = expected & set(returns)
+        return _live_view(
+            targeted, returns, done, dead, spinner, n_cells=n_cells, cells_for=cells_for
+        )
+
     # transient=False keeps the finished checklist on screen above the
     # rendered tables, as a persistent at-a-glance record of the run.
     with Live(console=console, refresh_per_second=12, transient=False) as live:
@@ -417,7 +463,7 @@ def _stream_state(call: Callable[..., dict[str, Any]], payload: dict[str, Any])
             now = time.monotonic()
             if len(done) != prev_done:
                 prev_done, last_change = len(done), now
-            live.update(_live_view(targeted, returns, done, dead, spinner))
+            live.update(view())
 
             if not expected - done:
                 break
@@ -431,7 +477,7 @@ def _stream_state(call: Callable[..., dict[str, Any]], payload: dict[str, Any])
                     dead |= gone
                     expected -= gone
                     last_change = now  # don't re-probe every single poll
-                    live.update(_live_view(targeted, returns, done, dead, spinner))
+                    live.update(view())
                     if not expected - done:
                         break
 
@@ -439,20 +485,36 @@ def _stream_state(call: Callable[..., dict[str, Any]], payload: dict[str, Any])
                 break
             time.sleep(_POLL_INTERVAL)
 
-    # Live view cleared — render the coloured tables, one block per minion.
-    _print_state_result({"return": [returns]})
+    return returns, dead, expected, start
+
+
+def _print_stragglers(dead: set[str], stalled: list[str]) -> None:
+    """The shared trailer for a streamed job: who never answered and who was
+    still running when the deadline tripped."""
     if dead:
         console.print(
-            f"[yellow]no response from: {', '.join(sorted(dead))} "
+            f"[yellow]no response from: {', '.join(sorted(dead, key=_natural_key))} "
             f"(down, or no longer running the job)[/]"
         )
-    stalled = sorted(expected - set(returns) - dead)
     if stalled:
         console.print(
             f"[yellow]still running at the {int(_POLL_DEADLINE)}s deadline: "
             f"{', '.join(stalled)}[/]"
         )
 
+
+def _stream_state(call: Callable[..., dict[str, Any]], payload: dict[str, Any]) -> None:
+    """Stream a state job, then render the coloured per-minion tables and a
+    fleet-wide summary."""
+    result = _stream_job(call, payload, n_cells=5, cells_for=_state_cells)
+    if result is None:
+        return
+    returns, dead, expected, start = result
+
+    # Live view cleared — render the coloured tables, one block per minion.
+    _print_state_result({"return": [returns]})
+    _print_stragglers(dead, sorted(expected - set(returns) - dead, key=_natural_key))
+
     # Fleet-wide summary: totals across all minions + wall-clock elapsed.
     totals, n = _grand_totals(returns)
     if n:
@@ -489,13 +551,22 @@ def run_state(args: argparse.Namespace, call: Callable[..., dict[str, Any]]) ->
 # --------------------------------------------------------------------------
 
 
+def _natural_key(name: str) -> list[object]:
+    """Sort key that orders embedded numbers numerically (bml2 before bml10)."""
+    return [int(p) if p.isdigit() else p for p in re.split(r"(\d+)", name)]
+
+
 def _print_key_panels(data: dict[str, Any]) -> None:
-    """Render key.list_all as one panel per acceptance status."""
-    panels: list[Panel] = []
+    """Render key.list_all as one stacked panel per acceptance status, the
+    IDs flowed into aligned columns inside each panel."""
     for status_key, (label, color) in _KEY_PANELS.items():
-        keys: list[str] = data.get(status_key, [])
-        body: Any = Text("\n".join(keys)) if keys else Text("(none)", style="dim")
-        panels.append(
+        keys: list[str] = sorted(data.get(status_key, []), key=_natural_key)
+        body: Any = (
+            Columns([Text(k) for k in keys], padding=(0, 2))
+            if keys
+            else Text("(none)", style="dim")
+        )
+        console.print(
             Panel(
                 body,
                 title=f"{label} ({len(keys)})",
@@ -503,7 +574,6 @@ def _print_key_panels(data: dict[str, Any]) -> None:
                 border_style=color,
             )
         )
-    console.print(Columns(panels, equal=True, expand=False))
 
 
 def run_keys(args: argparse.Namespace, call: Callable[..., dict[str, Any]]) -> None:
@@ -536,3 +606,113 @@ def run_keys(args: argparse.Namespace, call: Callable[..., dict[str, Any]]) -> N
         label = _KEY_PANELS.get(status_key, (status_key, "white"))[0]
         joined = ", ".join(ids) if ids else "[dim](none)[/]"
         console.print(f"{label}: {joined}")
+
+
+# --------------------------------------------------------------------------
+# command execution
+# --------------------------------------------------------------------------
+
+
+def _print_cmd_one(minion: str, val: Any) -> None:
+    """Render one minion's ``cmd.run_all`` reply: a bold id with its exit code
+    (green for 0, red otherwise), then stdout and any stderr indented beneath.
+
+    Falls back to printing the raw value for any non-dict shape — e.g. a
+    minion that errored before the command ran, where salt returns a string."""
+    if not isinstance(val, dict):
+        console.print(Text(minion, style="bold"))
+        console.print(Padding(Text(str(val)), (0, 0, 0, 2)))
+        return
+
+    record = cast("dict[str, Any]", val)
+    retcode = record.get("retcode")
+    header = Text(minion, style="bold")
+    if retcode == 0:
+        header.append("  exit 0", style="green")
+    elif retcode is not None:
+        header.append(f"  exit {retcode}", style="red")
+    console.print(header)
+
+    stdout = str(record.get("stdout", "")).rstrip()
+    stderr = str(record.get("stderr", "")).rstrip()
+    if stdout:
+        console.print(Padding(Text(stdout), (0, 0, 0, 2)))
+    if stderr:
+        console.print(Padding(Text("stderr:", style="red"), (0, 0, 0, 2)))
+        console.print(Padding(Text(stderr, style="red"), (0, 0, 0, 4)))
+    if not stdout and not stderr:
+        console.print(Padding(Text("(no output)", style="dim"), (0, 0, 0, 2)))
+
+
+def _print_cmd_result(resp: dict[str, Any]) -> None:
+    """Render a ``cmd.run_all`` reply, one block per minion (naturally sorted)."""
+    ret = _first_return(resp)
+    if not isinstance(ret, dict) or not ret:
+        console.print("(no minions responded)")
+        return
+    results = cast("dict[str, Any]", ret)
+    for minion in sorted(results, key=_natural_key):
+        _print_cmd_one(minion, results[minion])
+
+
+def _cmd_cells(val: Any) -> list[Text]:
+    """The single live-view column for a finished minion's ``cmd.run_all``
+    reply: its exit code, green for 0 and red otherwise."""
+    if isinstance(val, dict):
+        retcode = cast("dict[str, Any]", val).get("retcode")
+        if retcode == 0:
+            return [Text("exit 0", style="green")]
+        if retcode is not None:
+            return [Text(f"exit {retcode}", style="red")]
+    return [Text("(no output)", style="dim")]
+
+
+def _stream_cmd(call: Callable[..., dict[str, Any]], payload: dict[str, Any]) -> None:
+    """Stream a ``cmd.run_all`` job, then render each minion's output block and
+    a fleet-wide ok/failed summary."""
+    result = _stream_job(call, payload, n_cells=1, cells_for=_cmd_cells)
+    if result is None:
+        return
+    returns, dead, expected, start = result
+
+    _print_cmd_result({"return": [returns]})
+    _print_stragglers(dead, sorted(expected - set(returns) - dead, key=_natural_key))
+
+    n = len(returns)
+    if n:
+        ok = sum(
+            1
+            for v in returns.values()
+            if isinstance(v, dict) and cast("dict[str, Any]", v).get("retcode") == 0
+        )
+        fail = n - ok
+        wall = _fmt_duration((time.monotonic() - start) * 1000.0)
+        tally = f"[green]{ok} ok[/]   " + (
+            f"[red]{fail} failed[/]" if fail else f"{fail} failed"
+        )
+        console.print("[dim]===[/]")
+        console.print(f"[bold]{n} minion(s)[/]   {tally}   [dim]took {wall}[/]")
+
+
+def run_cmd(args: argparse.Namespace, call: Callable[..., dict[str, Any]]) -> None:
+    """The ``salt cmd`` command, layered over ``local_async`` + ``cmd.run_all``.
+
+    Runs a shell command on the targeted minions and streams the results: a
+    live per-minion checklist (spinner -> exit code) while the job runs, then a
+    readable block per minion (exit code, stdout, stderr) and an ok/failed
+    summary — instead of the raw JSON the low-level ``local`` command emits.
+    Like ``state``, it fires the job async and polls the runner so a slow or
+    wide command never holds one long connection open against the gateway cap.
+    Trailing ``key=value`` args are forwarded as kwargs to ``cmd.run_all``
+    (e.g. ``shell=powershell``, ``cwd=...``, ``runas=...``). ``call(name,
+    **kw)`` invokes the named salt-api client (cli.py binds it to the
+    configured connection)."""
+    pos, kw = split_args(list(getattr(args, "args", None) or []))
+    payload: dict[str, Any] = {
+        "tgt": args.target,
+        "fun": "cmd.run_all",
+        "arg": [args.cmdline, *pos],
+    }
+    if kw:
+        payload["kwarg"] = kw
+    _stream_cmd(call, payload)

salt_api_cli-1.4.1/salt_api_cli/version.py

@@ -0,0 +1 @@
+__version__ = "1.4.1"

{salt_api_cli-1.3.0 → salt_api_cli-1.4.1/salt_api_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: salt-api-cli
-Version: 1.3.0
+Version: 1.4.1
 Summary: CLI to access salt-api
 Author-email: Pradish Bijukchhe <pradish@sandbox.com.np>
 License-Expression: MIT
@@ -33,7 +33,7 @@ Commands come in two layers:
 
 - **Low-level** (`local`, `runner`, `wheel`) map directly to the salt-api
   clients and print **raw JSON**.
-- **High-level** (`state`, `keys`) wrap those clients and render
+- **High-level** (`cmd`, `state`, `keys`) wrap those clients and render
   **readable, colorized output** with `rich`.
 
 ## Installation
@@ -76,9 +76,9 @@ verbatim as indented JSON.
 
 ```
 # Local client — fan out to minions
-salt local '*' test.ping
-salt local 'bml*' cmd.run 'whoami'
-salt local 'bml1' cmd.run 'Get-Date' shell=powershell
+salt local "*" test.ping
+salt local "bml*" cmd.run whoami
+salt local "bml1" cmd.run "Get-Date" shell=powershell
 
 # Runner client (master-side: manage.status, jobs.list_jobs, ...)
 salt runner manage.status
@@ -93,20 +93,27 @@ salt wheel key.list_all
 These wrap the low-level clients and render their output with `rich`.
 
 ```
+# Run a shell command — a live per-minion checklist while it runs, then
+# one block per minion (exit code, stdout, stderr) and an ok/failed summary.
+# Fired async (local_async + cmd.run_all) and polled via the runner, like
+# `state`, so a slow or wide command never holds one long connection open.
+salt cmd "bml*" hostname
+salt cmd "bml1" "Get-Date" shell=powershell
+
 # State runs — a colored table of states, one row each, with a summary.
 # Driven by the local client + state.* functions.
-salt state highstate 'bml1'           # apply the highstate
-salt state test 'bml1'                # dry-run the highstate (forces test=True)
-salt state apply 'bml1' veyon         # apply specific sls module(s)
-salt state apply 'bml1' veyon.ldap test=True
+salt state highstate "bml1"           # apply the highstate
+salt state test "bml1"                # dry-run the highstate (forces test=True)
+salt state apply "bml1" veyon         # apply specific sls module(s)
+salt state apply "bml1" veyon.ldap test=True
 
 # Key management — wraps the wheel client's key.* functions.
 # `keys list` shows one colored panel per status (Accepted/Pending/Denied/Rejected).
 salt keys list
-salt keys accept <id-or-glob>
+salt keys accept "<id-or-glob>"
 salt keys accept-all
-salt keys reject <id-or-glob>
-salt keys delete <id-or-glob>
+salt keys reject "<id-or-glob>"
+salt keys delete "<id-or-glob>"
 ```
 
 Color and panels appear when writing to a terminal; output is plain when

salt_api_cli-1.3.0/salt_api_cli/version.py

@@ -1 +0,0 @@
-__version__ = "1.3.0"