kx-cli 0.0.6__tar.gz → 0.0.8__tar.gz

{kx_cli-0.0.6/src/kx_cli.egg-info → kx_cli-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kx-cli
-Version: 0.0.6
+Version: 0.0.8
 Summary: kubectl wrapper with index-based resource selection
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -9,7 +9,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: typer==0.26.8
+Requires-Dist: typer==0.27.0
 Requires-Dist: kubernetes
 Requires-Dist: rich
 Provides-Extra: dev
@@ -17,6 +17,8 @@ Requires-Dist: ruff; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: build
+Requires-Dist: pyinstaller; extra == "build"
 Dynamic: license-file
 
 <div align="center">
@@ -48,10 +50,42 @@ Dynamic: license-file
 
 ## Install
 
+Requires Python 3.11+ and `kubectl` on your PATH.
+
+With [uv](https://docs.astral.sh/uv/) (recommended):
+
+```bash
+uv tool install kx-cli
+```
+
+With [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install kx-cli
+```
+
+With pip:
+
 ```bash
 pip install kx-cli
 ```
 
+As a kubectl plugin via [krew](https://krew.sigs.k8s.io/), where kx is published as `idx` (no Python required; pending krew-index acceptance):
+
+```bash
+kubectl krew install idx
+alias kx="kubectl idx"
+```
+
+Standalone binaries (linux/macOS, amd64/arm64, no Python required) are attached to each [GitHub Release](https://github.com/jzills/kx/releases).
+
+Or try it without installing (the package is `kx-cli`, the command is `kx`):
+
+```bash
+uvx --from kx-cli kx get pods
+pipx run --spec kx-cli kx get pods
+```
+
 ## Usage
 
 ### List resources
@@ -60,7 +94,9 @@ pip install kx-cli
 kx get <resource> [--match|-m <substring>] [kubectl flags...]
 ```
 
-Fetches resources and assigns index numbers. Any extra flags (e.g. `-n <namespace>`, `-A`) are passed through to kubectl. Use `--match`/`-m` to filter results by name (substring, case-insensitive).
+Fetches resources and assigns index numbers. Any extra flags (e.g. `-n <namespace>`, `-A`) are passed through to kubectl. Use `--match`/`-m` to filter results by name (substring, case-insensitive). All-namespace listings (`-A`) are display-only — rows aren't indexed, since names aren't unique across namespaces; scope to a namespace to select.
+
+Known kinds can drop the `get`: `kx pods`, `kx deploy -n kube-system`, `kx svc --match api`. This covers the built-in kinds and their kubectl shorthands (`po`, `deploy`, `svc`, `sts`, ...); existing commands take precedence, so `kx ns 3` still switches namespaces (bare `kx ns` lists them). CRDs and other resource types still use `kx get <resource>`. An integer after a kind is an index into the current state: `kx po 3` (or `kx get po 3`) relists just that pod, erroring if index 3 isn't a pod. Multiple indexes work too: `kx po 1 3`.
 
 ```
 $ kx get pods
@@ -73,19 +109,19 @@ Pods · default · 3 items
 
 All subsequent commands reference resources by their `X` index from the last `kx get`.
 
-Global flags: `--no-color` disables styled output, `--version` prints the installed version, and `--help` on any command shows usage, examples, and aliases.
+Global flags: `--no-color` disables styled output, `-v`/`--version` prints the installed version, and `--help` on any command shows usage, examples, and aliases.
 
 ### Commands
 
 <!-- commands-table-start -->
 | Command | Description |
 |---|---|
-| `kx get <resource> [--match/-m text] [kubectl flags...]` | List resources and assign index numbers for use with other commands. |
+| `kx get <resource> [--match/-m str] [kubectl flags...]` | List resources and assign index numbers for use with other commands; shorthand: kx <kind> (e.g. kx pods, kx po 3). |
 | `kx describe <indexes>... [kubectl flags...]` | Show full kubectl describe output for one or more indexed resources. |
 | `kx events <indexes>...` | Show Kubernetes events for one or more indexed resources. |
 | `kx logs <index> [kubectl flags...]` | Stream logs for an indexed resource; aggregates across pods for Deployments, StatefulSets, DaemonSets, and Services. |
 | `kx labels <indexes>... [--selector/-s]` | Show labels for one or more indexed resources; --selector formats output as a label selector. |
-| `kx yaml <indexes>... [--show text]` | Print the raw YAML manifest for one or more indexed resources; --show filters to specific top-level fields. |
+| `kx yaml <indexes>... [--show str]` | Print the raw YAML manifest for one or more indexed resources; --show filters to specific top-level fields. |
 | `kx delete <indexes>... [--yes/-y]` | Delete one or more indexed resources (prompts for confirmation unless --yes). |
 | `kx edit <index> [kubectl flags...]` | Open an indexed resource in your editor via kubectl edit. |
 | `kx exec <index> [<cmd>...] [kubectl flags...]` | Open an interactive shell in an indexed pod (bash, falling back to sh). |
@@ -94,7 +130,7 @@ Global flags: `--no-color` disables styled output, `--version` prints the instal
 | `kx scale <index> <replicas>` | Scale an indexed Deployment, StatefulSet, or ReplicaSet to a given replica count. |
 | `kx port-forward <index> <port> [kubectl flags...]` | Forward a local port to an indexed resource (Pod, Deployment, ReplicaSet, StatefulSet, DaemonSet, Service). |
 | `kx diagnostic <index>` | Run read-only health diagnostics on an indexed Deployment, StatefulSet, DaemonSet, or Pod; alias: kx diag. |
-| `kx namespace <index>` | Switch to an indexed namespace; alias: kx ns (run kx get namespaces first). |
+| `kx namespace [<index>]` | List namespaces, or switch to an indexed one; alias: kx ns. |
 | `kx theme [<name>]` | List available color themes or persist a choice by name or index. |
 | `kx state [<position>] [--all/-a]` | Show current state, jump to a history position, or list all entries with --all. |
 | `kx drop <position>` | Remove a history entry by position (shown in kx state --all). |

{kx_cli-0.0.6 → kx_cli-0.0.8}/README.md

@@ -27,10 +27,42 @@
 
 ## Install
 
+Requires Python 3.11+ and `kubectl` on your PATH.
+
+With [uv](https://docs.astral.sh/uv/) (recommended):
+
+```bash
+uv tool install kx-cli
+```
+
+With [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install kx-cli
+```
+
+With pip:
+
 ```bash
 pip install kx-cli
 ```
 
+As a kubectl plugin via [krew](https://krew.sigs.k8s.io/), where kx is published as `idx` (no Python required; pending krew-index acceptance):
+
+```bash
+kubectl krew install idx
+alias kx="kubectl idx"
+```
+
+Standalone binaries (linux/macOS, amd64/arm64, no Python required) are attached to each [GitHub Release](https://github.com/jzills/kx/releases).
+
+Or try it without installing (the package is `kx-cli`, the command is `kx`):
+
+```bash
+uvx --from kx-cli kx get pods
+pipx run --spec kx-cli kx get pods
+```
+
 ## Usage
 
 ### List resources
@@ -39,7 +71,9 @@ pip install kx-cli
 kx get <resource> [--match|-m <substring>] [kubectl flags...]
 ```
 
-Fetches resources and assigns index numbers. Any extra flags (e.g. `-n <namespace>`, `-A`) are passed through to kubectl. Use `--match`/`-m` to filter results by name (substring, case-insensitive).
+Fetches resources and assigns index numbers. Any extra flags (e.g. `-n <namespace>`, `-A`) are passed through to kubectl. Use `--match`/`-m` to filter results by name (substring, case-insensitive). All-namespace listings (`-A`) are display-only — rows aren't indexed, since names aren't unique across namespaces; scope to a namespace to select.
+
+Known kinds can drop the `get`: `kx pods`, `kx deploy -n kube-system`, `kx svc --match api`. This covers the built-in kinds and their kubectl shorthands (`po`, `deploy`, `svc`, `sts`, ...); existing commands take precedence, so `kx ns 3` still switches namespaces (bare `kx ns` lists them). CRDs and other resource types still use `kx get <resource>`. An integer after a kind is an index into the current state: `kx po 3` (or `kx get po 3`) relists just that pod, erroring if index 3 isn't a pod. Multiple indexes work too: `kx po 1 3`.
 
 ```
 $ kx get pods
@@ -52,19 +86,19 @@ Pods · default · 3 items
 
 All subsequent commands reference resources by their `X` index from the last `kx get`.
 
-Global flags: `--no-color` disables styled output, `--version` prints the installed version, and `--help` on any command shows usage, examples, and aliases.
+Global flags: `--no-color` disables styled output, `-v`/`--version` prints the installed version, and `--help` on any command shows usage, examples, and aliases.
 
 ### Commands
 
 <!-- commands-table-start -->
 | Command | Description |
 |---|---|
-| `kx get <resource> [--match/-m text] [kubectl flags...]` | List resources and assign index numbers for use with other commands. |
+| `kx get <resource> [--match/-m str] [kubectl flags...]` | List resources and assign index numbers for use with other commands; shorthand: kx <kind> (e.g. kx pods, kx po 3). |
 | `kx describe <indexes>... [kubectl flags...]` | Show full kubectl describe output for one or more indexed resources. |
 | `kx events <indexes>...` | Show Kubernetes events for one or more indexed resources. |
 | `kx logs <index> [kubectl flags...]` | Stream logs for an indexed resource; aggregates across pods for Deployments, StatefulSets, DaemonSets, and Services. |
 | `kx labels <indexes>... [--selector/-s]` | Show labels for one or more indexed resources; --selector formats output as a label selector. |
-| `kx yaml <indexes>... [--show text]` | Print the raw YAML manifest for one or more indexed resources; --show filters to specific top-level fields. |
+| `kx yaml <indexes>... [--show str]` | Print the raw YAML manifest for one or more indexed resources; --show filters to specific top-level fields. |
 | `kx delete <indexes>... [--yes/-y]` | Delete one or more indexed resources (prompts for confirmation unless --yes). |
 | `kx edit <index> [kubectl flags...]` | Open an indexed resource in your editor via kubectl edit. |
 | `kx exec <index> [<cmd>...] [kubectl flags...]` | Open an interactive shell in an indexed pod (bash, falling back to sh). |
@@ -73,7 +107,7 @@ Global flags: `--no-color` disables styled output, `--version` prints the instal
 | `kx scale <index> <replicas>` | Scale an indexed Deployment, StatefulSet, or ReplicaSet to a given replica count. |
 | `kx port-forward <index> <port> [kubectl flags...]` | Forward a local port to an indexed resource (Pod, Deployment, ReplicaSet, StatefulSet, DaemonSet, Service). |
 | `kx diagnostic <index>` | Run read-only health diagnostics on an indexed Deployment, StatefulSet, DaemonSet, or Pod; alias: kx diag. |
-| `kx namespace <index>` | Switch to an indexed namespace; alias: kx ns (run kx get namespaces first). |
+| `kx namespace [<index>]` | List namespaces, or switch to an indexed one; alias: kx ns. |
 | `kx theme [<name>]` | List available color themes or persist a choice by name or index. |
 | `kx state [<position>] [--all/-a]` | Show current state, jump to a history position, or list all entries with --all. |
 | `kx drop <position>` | Remove a history entry by position (shown in kx state --all). |

{kx_cli-0.0.6 → kx_cli-0.0.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kx-cli"
-version = "0.0.6"
+version = "0.0.8"
 description = "kubectl wrapper with index-based resource selection"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -11,7 +11,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "typer==0.26.8",
+    "typer==0.27.0",
     "kubernetes",
     "rich",
 ]
@@ -23,6 +23,9 @@ dev = [
     "pytest",
     "pytest-cov",
 ]
+build = [
+    "pyinstaller",
+]
 
 [project.scripts]
 kx = "kx.main:app"

{kx_cli-0.0.6 → kx_cli-0.0.8}/src/kx/commands/delete.py

@@ -1,6 +1,8 @@
+from contextlib import nullcontext
+
 from kx.kubectl import KubectlServiceProtocol
 from kx.state import StateServiceProtocol
-from kx.types import Confirm
+from kx.types import Confirm, Status
 
 
 class DeleteCommand:
@@ -9,14 +11,19 @@ class DeleteCommand:
         state: StateServiceProtocol,
         kubectl: KubectlServiceProtocol,
         confirm: Confirm,
+        status: Status | None = None,
     ):
         self.state = state
         self.kubectl = kubectl
         self.confirm = confirm
+        self.status = status or (lambda _msg: nullcontext())
 
     def execute(self, index: int, yes: bool) -> str:
         name, namespace, kind = self.state.fields(index)
+        # The confirm prompt must stay outside the spinner: a prompt inside a
+        # Live region breaks input.
         if not yes:
             self.confirm(f"Delete {kind}/{name} in {namespace}?")
-        self.kubectl.run(["delete", kind, name, "-n", namespace])
+        with self.status("deleting"):
+            self.kubectl.run(["delete", kind, name, "-n", namespace])
         return f"Deleted {kind}/{name}"

{kx_cli-0.0.6 → kx_cli-0.0.8}/src/kx/commands/describe.py

@@ -1,4 +1,5 @@
 from kx.kubectl import KubectlServiceProtocol
+from kx.refresh import ensure_exists
 from kx.state import StateServiceProtocol
 
 
@@ -14,6 +15,8 @@ class DescribeCommand:
     def execute(self, index: int, extra_args: list[str] | None = None) -> None:
         extra_args = extra_args or []
         name, namespace, kind = self.state.fields(index)
-        self.kubectl.run_interactive(
+        rc = self.kubectl.run_interactive(
             ["describe", kind, name, "-n", namespace, *extra_args]
         )
+        if rc != 0:
+            ensure_exists(self.kubectl, kind, name, namespace)

{kx_cli-0.0.6 → kx_cli-0.0.8}/src/kx/commands/edit.py

@@ -1,4 +1,5 @@
 from kx.kubectl import KubectlServiceProtocol
+from kx.refresh import ensure_exists
 from kx.state import StateServiceProtocol
 
 
@@ -10,4 +11,8 @@ class EditCommand:
     def execute(self, index: int, extra_args: list[str] | None = None) -> None:
         extra_args = extra_args or []
         name, namespace, kind = self.state.fields(index)
-        self.kubectl.run_interactive(["edit", kind, name, "-n", namespace, *extra_args])
+        rc = self.kubectl.run_interactive(
+            ["edit", kind, name, "-n", namespace, *extra_args]
+        )
+        if rc != 0:
+            ensure_exists(self.kubectl, kind, name, namespace)

{kx_cli-0.0.6 → kx_cli-0.0.8}/src/kx/commands/events.py

@@ -1,11 +1,19 @@
 from kx.events import EventsServiceProtocol
+from kx.kubectl import KubectlServiceProtocol
+from kx.refresh import ensure_exists
 from kx.state import StateServiceProtocol
 
 
 class EventsCommand:
-    def __init__(self, state: StateServiceProtocol, events: EventsServiceProtocol):
+    def __init__(
+        self,
+        state: StateServiceProtocol,
+        events: EventsServiceProtocol,
+        kubectl: KubectlServiceProtocol,
+    ):
         self.state = state
         self.events = events
+        self.kubectl = kubectl
 
     def execute(self, index: int) -> str:
         name, namespace, kind = self.state.fields(index)
@@ -13,6 +21,9 @@ class EventsCommand:
         filtered = self.events.filter(all_events, name, kind)
 
         if not filtered:
+            # Deleted resources keep their events ~1h; only an empty result
+            # warrants checking whether the target itself is gone.
+            ensure_exists(self.kubectl, kind, name, namespace)
             return "No events found"
 
         output = []

{kx_cli-0.0.6 → kx_cli-0.0.8}/src/kx/commands/exec.py

@@ -2,6 +2,7 @@ import subprocess
 
 from kx.kinds import Kind
 from kx.kubectl import KubectlServiceProtocol
+from kx.refresh import ensure_exists
 from kx.state import StateServiceProtocol
 
 
@@ -29,6 +30,7 @@ class ExecCommand:
                 stderr=subprocess.DEVNULL,
             )
             if rc != 0:
+                ensure_exists(self.kubectl, str(Kind.Pod), name, namespace)
                 raise ValueError(f"Command failed in container (exit {rc}).")
         else:
             for shell in self.shells:
@@ -50,6 +52,7 @@ class ExecCommand:
                         ["exec", "-it", name, "-n", namespace, *extra_args, "--", shell]
                     )
                     return
+            ensure_exists(self.kubectl, str(Kind.Pod), name, namespace)
             raise ValueError(
                 "No shell found in container. Provide an explicit command: kx exec <index> -- /path/to/binary"
             )

{kx_cli-0.0.6 → kx_cli-0.0.8}/src/kx/commands/get.py

@@ -1,7 +1,7 @@
 from kx.index import IndexServiceProtocol
 from kx.kinds import normalize_kind
 from kx.kubectl import KubectlServiceProtocol
-from kx.state import State, StateServiceProtocol
+from kx.state import Query, State, StateServiceProtocol
 
 
 def _extract_namespace(extra_args: list[str]) -> str | None:
@@ -34,14 +34,23 @@ class GetCommand:
         output = self.kubectl.run(["get", resource, *extra_args])
         if filter_term:
             output = self.index.filter(output, filter_term)
-        indexed_output, names = self.index.add(output)
         all_namespaces = any(arg in ("-A", "--all-namespaces") for arg in extra_args)
-        if names and not all_namespaces:
+        if all_namespaces:
+            # Names aren't unique across namespaces, so `-A` results are never
+            # indexed — returning unindexed output keeps dead X numbers off
+            # the screen.
+            return output
+        indexed_output, names = self.index.add(output)
+        if names:
             namespace = (
                 _extract_namespace(extra_args) or self.kubectl.current_namespace()
             )
             kind = normalize_kind(resource)
             self.state.save(
-                State(resources={name: kind for name in names}, namespace=namespace)
+                State(
+                    resources={name: kind for name in names},
+                    namespace=namespace,
+                    query=Query(resource=resource, args=extra_args, match=filter_term),
+                )
             )
         return indexed_output

{kx_cli-0.0.6 → kx_cli-0.0.8}/src/kx/commands/logs.py

@@ -1,22 +1,35 @@
 import json
+from contextlib import nullcontext
 
 from kx.kinds import Kind
 from kx.kubectl import KubectlServiceProtocol
+from kx.refresh import ensure_exists
 from kx.state import StateServiceProtocol
+from kx.types import Status
 
 _AGGREGATE_KINDS = {Kind.Deployment, Kind.StatefulSet, Kind.DaemonSet, Kind.Service}
 
 
 class LogsCommand:
-    def __init__(self, state: StateServiceProtocol, kubectl: KubectlServiceProtocol):
+    def __init__(
+        self,
+        state: StateServiceProtocol,
+        kubectl: KubectlServiceProtocol,
+        status: Status | None = None,
+    ):
         self.state = state
         self.kubectl = kubectl
+        self.status = status or (lambda _msg: nullcontext())
 
     def execute(self, index: int, extra_args: list[str] | None = None) -> None:
         extra_args = extra_args or []
         name, namespace, kind = self.state.fields(index)
         if kind == Kind.Pod:
-            self.kubectl.run_interactive(["logs", name, "-n", namespace, *extra_args])
+            rc = self.kubectl.run_interactive(
+                ["logs", name, "-n", namespace, *extra_args]
+            )
+            if rc != 0:
+                ensure_exists(self.kubectl, kind, name, namespace)
         elif kind in _AGGREGATE_KINDS:
             selector = self._selector(name, namespace, kind)
             self.kubectl.run_interactive(
@@ -26,7 +39,8 @@ class LogsCommand:
             raise ValueError(f"Logs are not supported for '{kind}'.")
 
     def _selector(self, name: str, namespace: str, kind: str) -> str:
-        raw = self.kubectl.run(["get", kind, name, "-n", namespace, "-o", "json"])
+        with self.status("resolving pod selector"):
+            raw = self.kubectl.run(["get", kind, name, "-n", namespace, "-o", "json"])
         obj = json.loads(raw)
         labels = self._extract_labels(obj, kind)
         if not labels:

{kx_cli-0.0.6 → kx_cli-0.0.8}/src/kx/commands/port_forward.py

@@ -1,5 +1,6 @@
 from kx.kinds import Kind
 from kx.kubectl import KubectlServiceProtocol
+from kx.refresh import ensure_exists
 from kx.state import StateServiceProtocol
 
 _SUPPORTED_KINDS = {
@@ -24,6 +25,8 @@ class PortForwardCommand:
         name, namespace, kind = self.state.fields(index)
         if kind not in _SUPPORTED_KINDS:
             raise ValueError(f"port-forward is not supported for '{kind}'.")
-        self.kubectl.run_interactive(
+        rc = self.kubectl.run_interactive(
             ["port-forward", f"{kind}/{name}", port, "-n", namespace, *extra_args]
         )
+        if rc != 0:
+            ensure_exists(self.kubectl, kind, name, namespace)

{kx_cli-0.0.6 → kx_cli-0.0.8}/src/kx/console.py

@@ -1,6 +1,7 @@
 import re
 import json
-from contextlib import nullcontext
+import threading
+from contextlib import contextmanager
 from datetime import datetime, timezone
 
 import typer
@@ -88,7 +89,7 @@ def print_success(msg: str) -> None:
 
 def print_error(msg: str) -> None:
     styled = re.sub(r"'([^']+)'", "[accent]'\\1'[/accent]", msg)
-    _console.print(f"[header]✗[/header] [body]{styled}[/body]")
+    _console.print(f"[error]✗[/error] [body]{styled}[/body]")
 
 
 def print_banner(kind: str, name: str, namespace: str = "", extra: str = "") -> None:
@@ -100,12 +101,56 @@ def print_banner(kind: str, name: str, namespace: str = "", extra: str = "") ->
     _console.print(f"[muted]{' · '.join(parts)}[/muted]")
 
 
+# How long a command runs silently before the spinner appears. Quick commands
+# intentionally show nothing — a spinner that flashes for a fraction of a
+# second is noise, not feedback.
+_SPINNER_DELAY = 0.2
+
+
+@contextmanager
 def status(message: str):
-    """Spinner shown while waiting on the cluster; a no-op off-terminal so
-    piped output and test captures never receive spinner frames."""
+    """Spinner shown while waiting on the cluster, only once the command has
+    run for _SPINNER_DELAY. A no-op off-terminal so piped output and test
+    captures never receive spinner frames."""
     if not _console.is_terminal:
-        return nullcontext()
-    return _console.status(f"[muted]{message}…[/muted]", spinner_style="muted")
+        yield
+        return
+    # Low refresh with a matching spinner speed: roughly one frame per redraw,
+    # so the line isn't rewritten faster than the animation advances (the
+    # default 12.5 fps redraw flickers on some terminals).
+    live_status = _console.status(
+        f"[muted]{message}…[/muted]",
+        spinner_style="muted",
+        refresh_per_second=4,
+        speed=0.4,
+    )
+    lock = threading.Lock()
+    started = False
+    finished = False
+
+    def show() -> None:
+        nonlocal started
+        with lock:
+            if finished:
+                return
+            started = True
+            live_status.start()
+            # Status.start() schedules the first paint a full refresh interval
+            # out (250ms at 4 fps); paint now — the delay has already passed.
+            live_status._live.refresh()
+
+    timer = threading.Timer(_SPINNER_DELAY, show)
+    timer.start()
+    try:
+        yield
+    finally:
+        timer.cancel()
+        # The lock closes the race where the timer has fired but show() hasn't
+        # started the spinner yet, which would otherwise leave it running.
+        with lock:
+            finished = True
+            if started:
+                live_status.stop()
 
 
 def confirm(message: str) -> None:
@@ -147,7 +192,9 @@ def _print_get_caption(resource_type: str, namespace: str, count: int) -> None:
     )
 
 
-def render_indexed_table(text: str, resource_type: str, namespace: str) -> None:
+def render_indexed_table(
+    text: str, resource_type: str, namespace: str, note: str | None = None
+) -> None:
     lines = [line for line in text.splitlines() if line.strip()]
     if not lines:
         # kubectl exits 0 with empty stdout when nothing matches ("No
@@ -157,7 +204,7 @@ def render_indexed_table(text: str, resource_type: str, namespace: str) -> None:
 
     header_line = lines[0]
     first_col = header_line.split()[0] if header_line.split() else ""
-    if first_col != "X":
+    if first_col != "X" and note is None:
         _console.print(text, markup=False, highlight=False)
         return
 
@@ -222,6 +269,8 @@ def render_indexed_table(text: str, resource_type: str, namespace: str) -> None:
 
     _print_get_caption(resource_type, namespace, len(rows))
     _console.print(table)
+    if note:
+        _console.print(f"[muted]{note}[/muted]")
 
 
 def render_events_table(text: str) -> None:
@@ -505,7 +554,9 @@ def print_version(version: str) -> None:
     _console.print(f"kx {version}", markup=False, highlight=False)
 
 
-def print_help(sections: list[tuple[str, list[tuple[str, str]]]]) -> None:
+def print_help(
+    sections: list[tuple[str, list[tuple[str, str]]]], version: str | None = None
+) -> None:
     _console.print()
     for line in _KX_ART:
         _console.print(line, style="header", markup=False, highlight=False)
@@ -526,11 +577,14 @@ def print_help(sections: list[tuple[str, list[tuple[str, str]]]]) -> None:
         f"  [body]{'--no-color':<14}[/body]  [muted]Disable styled output.[/muted]"
     )
     _console.print(
-        f"  [body]{'--version':<14}[/body]  [muted]Show the kx version and exit.[/muted]"
+        f"  [body]{'-v, --version':<14}[/body]  [muted]Show the kx version and exit.[/muted]"
     )
     _console.print(
         f"  [body]{'--help':<14}[/body]  [muted]Show this message and exit.[/muted]"
     )
+    if version:
+        _console.print()
+        _console.print(f"[muted]v{version}[/muted]")
 
 
 _SWATCH_PARTS = (

kx_cli-0.0.8/src/kx/errors.py

@@ -0,0 +1,80 @@
+import functools
+from typing import Callable
+
+import typer
+from kubernetes.client.exceptions import ApiException
+
+from kx import console
+from kx.refresh import RefreshService, StaleResourceError
+
+_refresh_provider: Callable[[], RefreshService] | None = None
+
+
+def set_refresh(provider: Callable[[], RefreshService]) -> None:
+    """Register a factory for the RefreshService used on stale-state failures.
+
+    A factory (not an instance) so the service is built per failure from the
+    caller's current service objects — tests patch those with mocks.
+    """
+    global _refresh_provider
+    _refresh_provider = provider
+
+
+def _message(error: BaseException) -> str:
+    if isinstance(error, ApiException):
+        return f"Kubernetes API error: {error.status} {error.reason}"
+    return str(error)
+
+
+def _try_refresh(error: BaseException) -> None:
+    """If the failure means the indexed resource is gone, re-run the entry's
+    saved query and render the fresh list so the user can pick a new index."""
+    if _refresh_provider is None:
+        return
+    refresh = _refresh_provider()
+    if not refresh.matches(error):
+        return
+    try:
+        recovered = refresh.recover()
+    except (RuntimeError, ValueError, ApiException):
+        return
+    if recovered is None:
+        console.print_raw("Run 'kx get <resource>' to refresh the list.")
+        return
+    table, resource, namespace = recovered
+    console.print_raw("State was stale — refreshed, pick a new index:")
+    console.render_indexed_table(table, resource, namespace)
+
+
+def handle_errors(func=None, *, refresh: bool = True):
+    """Render expected command failures as a styled error and exit 1.
+
+    Wraps a Typer command so that `RuntimeError` (e.g. a non-zero kubectl exit or
+    missing state), `ValueError` (unsupported kind, bad argument), and the
+    Kubernetes SDK's `ApiException` are shown via `console.print_error` instead of
+    surfacing as a traceback. When the error signals a stale state entry (the
+    indexed resource no longer exists), the entry's saved query is re-run and the
+    refreshed list rendered. Commands that don't always consume an index (`get`)
+    pass `refresh=False` — message-sniffed NotFounds are then ignored, but an
+    explicit `StaleResourceError` still triggers the refresh. `typer.Exit`
+    and `typer.Abort` are not caught, so control-flow exits and confirmation
+    aborts pass through untouched. `functools.wraps` preserves `__wrapped__` so
+    Typer still reads the original signature.
+    """
+
+    def decorate(inner):
+        @functools.wraps(inner)
+        def wrapper(*args, **kwargs):
+            try:
+                return inner(*args, **kwargs)
+            except (RuntimeError, ValueError, ApiException) as e:
+                console.print_error(_message(e))
+                if refresh or isinstance(e, StaleResourceError):
+                    _try_refresh(e)
+                raise typer.Exit(1)
+
+        return wrapper
+
+    if func is not None:
+        return decorate(func)
+    return decorate

{kx_cli-0.0.6 → kx_cli-0.0.8}/src/kx/kinds.py

@@ -81,6 +81,10 @@ _PLURAL_DISPLAY: dict[Kind, str] = {
 }
 
 
+def is_kind_spelling(token: str) -> bool:
+    return token.lower() in _KIND_MAP
+
+
 def normalize_kind(resource_type: str) -> Kind | str:
     return _KIND_MAP.get(resource_type.lower(), resource_type)