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

salt_api_cli-1.3.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: salt-api-cli
+Version: 1.3.0
+Summary: CLI to access salt-api
+Author-email: Pradish Bijukchhe <pradish@sandbox.com.np>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sandbox-pokhara/saltapi-cli
+Project-URL: Issues, https://github.com/sandbox-pokhara/saltapi-cli/issues
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typeguard>=4.5.2
+Provides-Extra: pre-commit
+Requires-Dist: pre-commit; extra == "pre-commit"
+
+# salt-api-cli
+
+Thin Python CLI for [salt-api](https://docs.saltproject.io/en/latest/ref/netapi/all/salt.netapi.rest_cherrypy.html).
+Depends only on the standard library plus [`rich`](https://github.com/Textualize/rich)
+(readable output) and [`typeguard`](https://github.com/agronholm/typeguard)
+(JSON validation).
+
+Logs in once with PAM credentials, caches the token in
+`~/.cache/salt-api-cli/token.json`, then invokes salt-api's `local`,
+`runner`, and `wheel` clients over HTTPS. The cached token self-heals:
+it is refreshed proactively when its stored expiry has passed, and
+reactively when the server rejects it (e.g. after the salt-master
+container restarts and wipes its session store) — on rejection the CLI
+discards the token, logs in again, and retries the request once.
+
+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
+  **readable, colorized output** with `rich`.
+
+## Installation
+
+```
+pip install salt-api-cli
+```
+
+## Configuration
+
+Configuration is resolved in this order (later sources override earlier):
+
+1. `~/.saltapiclirc` — INI file, `[salt-api-cli]` section
+2. Environment variables — `SALT_API_URL`, `SALT_API_USER`, `SALT_API_PASS`, `SALT_API_INSECURE`
+3. Command-line flags — `--url`, `--user`, `--password`, `--insecure`, `--relogin`, `--no-token-cache`
+
+Example `~/.saltapiclirc`:
+
+```ini
+[salt-api-cli]
+url = https://salt.example.com
+user = salt_api
+password = secret
+insecure = false
+```
+
+`SALT_API_INSECURE=1` (or `insecure = true` in the config) skips TLS
+certificate verification.
+
+Token cache control: `--relogin` ignores any cached token and logs in
+fresh (re-caching the new token); `--no-token-cache` neither reads nor
+writes the cache for that run; `salt logout` discards the cached token.
+
+## Usage
+
+### Low-level commands (raw JSON)
+
+These map one-to-one to the salt-api clients and print the response
+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
+
+# Runner client (master-side: manage.status, jobs.list_jobs, ...)
+salt runner manage.status
+salt runner jobs.list_jobs
+
+# Wheel client (master-side, low-level)
+salt wheel key.list_all
+```
+
+### High-level commands (readable, colorized)
+
+These wrap the low-level clients and render their output with `rich`.
+
+```
+# 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
+
+# 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-all
+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
+piped to a file or pager.
+
+Any `key=value` argument is parsed as a kwarg to the salt function;
+anything else is positional.
+
+You can also invoke the CLI as a module: `python -m salt_api_cli ...`.
+
+## License
+
+This project is licensed under the terms of the MIT license.

salt_api_cli-1.3.0/README.md

@@ -0,0 +1,106 @@
+# salt-api-cli
+
+Thin Python CLI for [salt-api](https://docs.saltproject.io/en/latest/ref/netapi/all/salt.netapi.rest_cherrypy.html).
+Depends only on the standard library plus [`rich`](https://github.com/Textualize/rich)
+(readable output) and [`typeguard`](https://github.com/agronholm/typeguard)
+(JSON validation).
+
+Logs in once with PAM credentials, caches the token in
+`~/.cache/salt-api-cli/token.json`, then invokes salt-api's `local`,
+`runner`, and `wheel` clients over HTTPS. The cached token self-heals:
+it is refreshed proactively when its stored expiry has passed, and
+reactively when the server rejects it (e.g. after the salt-master
+container restarts and wipes its session store) — on rejection the CLI
+discards the token, logs in again, and retries the request once.
+
+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
+  **readable, colorized output** with `rich`.
+
+## Installation
+
+```
+pip install salt-api-cli
+```
+
+## Configuration
+
+Configuration is resolved in this order (later sources override earlier):
+
+1. `~/.saltapiclirc` — INI file, `[salt-api-cli]` section
+2. Environment variables — `SALT_API_URL`, `SALT_API_USER`, `SALT_API_PASS`, `SALT_API_INSECURE`
+3. Command-line flags — `--url`, `--user`, `--password`, `--insecure`, `--relogin`, `--no-token-cache`
+
+Example `~/.saltapiclirc`:
+
+```ini
+[salt-api-cli]
+url = https://salt.example.com
+user = salt_api
+password = secret
+insecure = false
+```
+
+`SALT_API_INSECURE=1` (or `insecure = true` in the config) skips TLS
+certificate verification.
+
+Token cache control: `--relogin` ignores any cached token and logs in
+fresh (re-caching the new token); `--no-token-cache` neither reads nor
+writes the cache for that run; `salt logout` discards the cached token.
+
+## Usage
+
+### Low-level commands (raw JSON)
+
+These map one-to-one to the salt-api clients and print the response
+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
+
+# Runner client (master-side: manage.status, jobs.list_jobs, ...)
+salt runner manage.status
+salt runner jobs.list_jobs
+
+# Wheel client (master-side, low-level)
+salt wheel key.list_all
+```
+
+### High-level commands (readable, colorized)
+
+These wrap the low-level clients and render their output with `rich`.
+
+```
+# 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
+
+# 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-all
+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
+piped to a file or pager.
+
+Any `key=value` argument is parsed as a kwarg to the salt function;
+anything else is positional.
+
+You can also invoke the CLI as a module: `python -m salt_api_cli ...`.
+
+## License
+
+This project is licensed under the terms of the MIT license.

{salt_api_cli-1.1.0 → salt_api_cli-1.3.0}/pyproject.toml

@@ -12,6 +12,7 @@ license = "MIT"
 keywords = []
 classifiers = ["Programming Language :: Python :: 3"]
 dependencies = [
+    "rich>=15.0.0",
     "typeguard>=4.5.2",
 ]
 dynamic = ["version"]

salt_api_cli-1.3.0/salt_api_cli/cli.py

@@ -0,0 +1,204 @@
+"""salt-api-cli — thin Python CLI for salt-api.
+
+Logs in once with PAM creds, caches the token in
+~/.cache/salt-api-cli/token.json, then invokes the salt-api local/
+runner/wheel clients over HTTPS. Depends only on the stdlib plus
+``typeguard`` for validating cached/responded JSON.
+
+This module is the CLI glue: it parses arguments and dispatches each
+command, wiring the low-level transport (:mod:`salt_api_cli.lowlevel`) to
+the high-level human-readable rendering (:mod:`salt_api_cli.highlevel`).
+
+The cached token self-heals: it is refreshed proactively when its stored
+expiry has passed, and reactively when the server rejects it (HTTP 401 or
+an EAUTH body) — e.g. after the salt-master container restarts and wipes
+its session store. `--relogin` forces a fresh login, `--no-token-cache`
+skips the cache entirely, and the `logout` subcommand discards the token.
+
+Configuration (later sources override earlier):
+    1. ~/.saltapiclirc                    INI file, [salt-api-cli] section
+    2. environment variables              SALT_API_URL, SALT_API_USER,
+                                          SALT_API_PASS, SALT_API_INSECURE
+    3. command-line flags                 --url, --user, --password,
+                                          --insecure, --relogin,
+                                          --no-token-cache
+
+Any `key=value` argument to local/runner/wheel is parsed as a kwarg to
+the salt function. Anything else is positional.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any
+
+from salt_api_cli import highlevel
+from salt_api_cli.lowlevel import (
+    TOKEN_FILE,
+    Config,
+    SaltApiError,
+    call,
+    clear_token,
+    load_config,
+    split_args,
+)
+
+
+def _run_local(cfg: Config, args: argparse.Namespace) -> None:
+    pos, kw = split_args(list(args.args))
+    payload: dict[str, Any] = {"tgt": args.target, "fun": args.function, "arg": pos}
+    if kw:
+        payload["kwarg"] = kw
+    print(json.dumps(call(cfg, "local", **payload), indent=2))
+
+
+def _run_client(cfg: Config, client: str, args: argparse.Namespace) -> None:
+    pos, kw = split_args(list(args.args))
+    payload: dict[str, Any] = {"fun": args.function, "arg": pos}
+    if kw:
+        payload["kwarg"] = kw
+    print(json.dumps(call(cfg, client, **payload), indent=2))
+
+
+def _run_state(cfg: Config, args: argparse.Namespace) -> None:
+    def client(name: str, **kw: Any) -> dict[str, Any]:
+        return call(cfg, name, **kw)
+
+    highlevel.run_state(args, client)
+
+
+def _run_keys(cfg: Config, args: argparse.Namespace) -> None:
+    def wheel(**kw: Any) -> dict[str, Any]:
+        return call(cfg, "wheel", **kw)
+
+    highlevel.run_keys(args, wheel)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="salt",
+        description="Thin Python CLI for salt-api.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "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 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 keys list\n"
+            "  salt keys accept '<id-or-glob>'\n"
+            "  salt keys accept-all\n"
+        ),
+    )
+    parser.add_argument("--url", help="salt-api base URL")
+    parser.add_argument("--user", help="PAM username")
+    parser.add_argument("--password", help="PAM password")
+    parser.add_argument(
+        "--insecure",
+        action="store_true",
+        help="skip TLS certificate verification",
+    )
+    parser.add_argument(
+        "--relogin",
+        action="store_true",
+        help="ignore any cached token and log in fresh (re-caches the new token)",
+    )
+    parser.add_argument(
+        "--no-token-cache",
+        dest="no_token_cache",
+        action="store_true",
+        help="do not read or write the token cache for this run",
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_local = sub.add_parser("local", help="run a function on minions")
+    p_local.add_argument("target", help="minion target (id or glob)")
+    p_local.add_argument("function", help="salt function (e.g. test.ping)")
+    p_local.add_argument(
+        "args", nargs=argparse.REMAINDER, help="positional and key=value args"
+    )
+
+    p_runner = sub.add_parser("runner", help="invoke a master-side runner")
+    p_runner.add_argument("function")
+    p_runner.add_argument("args", nargs=argparse.REMAINDER)
+
+    p_wheel = sub.add_parser("wheel", help="invoke a master-side wheel function")
+    p_wheel.add_argument("function")
+    p_wheel.add_argument("args", nargs=argparse.REMAINDER)
+
+    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")
+    p_highstate.add_argument("target", help="minion target (id or glob)")
+    p_highstate.add_argument(
+        "args", nargs=argparse.REMAINDER, help="key=value args, e.g. test=True"
+    )
+    p_test = state_sub.add_parser(
+        "test", help="dry-run the highstate (forces test=True)"
+    )
+    p_test.add_argument("target", help="minion target (id or glob)")
+    p_test.add_argument("args", nargs=argparse.REMAINDER, help="extra key=value args")
+    p_apply = state_sub.add_parser("apply", help="apply specific sls module(s)")
+    p_apply.add_argument("target", help="minion target (id or glob)")
+    p_apply.add_argument("sls", help="sls module to apply (e.g. veyon or veyon.ldap)")
+    p_apply.add_argument(
+        "args", nargs=argparse.REMAINDER, help="key=value args, e.g. test=True"
+    )
+
+    p_keys = sub.add_parser("keys", help="manage minion keys")
+    keys_sub = p_keys.add_subparsers(dest="action", required=True)
+    keys_sub.add_parser("list", help="show keys grouped by status")
+    p_accept = keys_sub.add_parser("accept", help="accept a key by id or glob")
+    p_accept.add_argument("match")
+    keys_sub.add_parser("accept-all", help="accept every pending key")
+    p_reject = keys_sub.add_parser("reject", help="reject a key by id or glob")
+    p_reject.add_argument("match")
+    p_delete = keys_sub.add_parser("delete", help="delete a key by id or glob")
+    p_delete.add_argument("match")
+
+    sub.add_parser("logout", help="discard the cached auth token")
+
+    return parser
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    # logout needs no server config — it just drops the local token file.
+    if args.command == "logout":
+        existed = TOKEN_FILE.exists()
+        clear_token()
+        print(
+            f"discarded cached token ({TOKEN_FILE})"
+            if existed
+            else f"no cached token to discard ({TOKEN_FILE})"
+        )
+        return
+
+    cfg = load_config(args)
+
+    try:
+        if args.command == "local":
+            _run_local(cfg, args)
+        elif args.command == "runner":
+            _run_client(cfg, "runner", args)
+        elif args.command == "wheel":
+            _run_client(cfg, "wheel", args)
+        elif args.command == "state":
+            _run_state(cfg, args)
+        elif args.command == "keys":
+            _run_keys(cfg, args)
+    except SaltApiError as e:
+        raise SystemExit(str(e))
+
+
+if __name__ == "__main__":
+    main()