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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kx-cli
-Version: 0.0.8
+Version: 0.0.10
 Summary: kubectl wrapper with index-based resource selection
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -70,7 +70,7 @@ With pip:
 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):
+As a kubectl plugin via [krew](https://krew.sigs.k8s.io/), where kx is published as `idx` (no Python required):
 
 ```bash
 kubectl krew install idx
@@ -88,26 +88,9 @@ pipx run --spec kx-cli kx get pods
 
 ## Usage
 
-### List resources
+`kx get <resource>` fetches resources and assigns each row an index; every other command takes those indexes. Extra flags pass through to kubectl (`-n <namespace>`, selectors, ...), and `--match`/`-m` filters rows by name substring. All-namespace listings (`-A`) are display-only — names aren't unique across namespaces.
 
-```
-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). 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
-Pods · default · 3 items
-  X    NAME                      READY    STATUS     RESTARTS    AGE
-  1    api-7d9f4b8c6-xkp2q       1/1      Running    0            2d
-  2    worker-6c8b5f7d9-mnt4r    1/1      Running    3            5h
-  3    postgres-0                1/1      Running    0           12d
-```
-
-All subsequent commands reference resources by their `X` index from the last `kx get`.
+Known kinds can drop the `get`: `kx pods`, `kx deploy -n kube-system`, `kx svc --match api` — kubectl shorthands (`po`, `deploy`, `svc`, `sts`, ...) included. An integer after a kind relists just that index: `kx po 3`. CRDs and other resource types still use `kx get <resource>`.
 
 Global flags: `--no-color` disables styled output, `-v`/`--version` prints the installed version, and `--help` on any command shows usage, examples, and aliases.
 
@@ -117,10 +100,15 @@ Global flags: `--no-color` disables styled output, `-v`/`--version` prints the i
 | Command | Description |
 |---|---|
 | `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 top [--match/-m str] [--no-limits] [kubectl flags...]` | List CPU/memory usage for pods in the current namespace and assign index numbers, like kx get; shows usage as a percent of each pod's resource limits unless --no-limits. |
 | `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 scan [<index>] [--engine str] [--full] [kubectl flags...]` | Scan the unique container images of an indexed workload for vulnerabilities, or the whole namespace when no index is given; prints a severity summary table by default, or the raw scanner output with --full. |
 | `kx labels <indexes>... [--selector/-s]` | Show labels for one or more indexed resources; --selector formats output as a label selector. |
+| `kx annotations <indexes>...` | Show annotations for one or more indexed resources. |
+| `kx label <index> [<pairs>...] [--remove str] [--overwrite]` | Set or remove labels on an indexed resource. |
+| `kx annotate <index> [<pairs>...] [--remove str] [--overwrite]` | Set or remove annotations on an indexed resource. |
 | `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. |
@@ -129,8 +117,9 @@ Global flags: `--no-color` disables styled output, `-v`/`--version` prints the i
 | `kx rollout <action> <index>` | Run a rollout action (status, restart, pause, resume, history, undo) on a Deployment, StatefulSet, or DaemonSet. |
 | `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 diagnostic [<index>]` | Diagnose an indexed Deployment, StatefulSet, DaemonSet, Job, CronJob, Service, PersistentVolumeClaim, or Pod, or triage the whole namespace when no index is given; alias: kx diag. |
 | `kx namespace [<index>]` | List namespaces, or switch to an indexed one; alias: kx ns. |
+| `kx context [<index>]` | List kubeconfig contexts, or switch to an indexed one; alias: kx contexts. |
 | `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). |
@@ -138,48 +127,41 @@ Global flags: `--no-color` disables styled output, `-v`/`--version` prints the i
 | `kx forward` | Navigate to the next kx get result. |
 <!-- commands-table-end -->
 
-### Example workflow
+### Triage a namespace
 
-```bash
-# list deployments, pick index 2
-kx get deployments
-kx describe 2
-
-# check events on that deployment
-kx events 2
-
-# drill into a pod
-kx get pods
-kx logs 1
-kx exec 1            # opens bash/sh
-kx exec 1 -- env     # run a specific command
-
-# forward local port 8080 to port 80 on a service
-kx get services
-kx port-forward 2 8080:80
-
-# navigate history after multiple gets
-kx get pods
-kx get deployments
-kx logs 1            # logs from pod index 1
-kx state --all       # review full history
-
-# clean up
-kx delete 3
-```
+Bare `kx diag` sweeps the current namespace — Deployments, StatefulSets,
+DaemonSets, Jobs, CronJobs, Services, and PersistentVolumeClaims, plus pods
+nothing owns — and prints a ranked table of what's unhealthy. Findings also
+draw on live resource usage (`kx top`): a pod running hot against its memory
+limit is flagged as an OOMKill risk before it dies. The rows are indexed, so
+`kx diag 1` or `kx logs 2` drill straight in.
 
-## State
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jzills/kx/main/demo/diag.gif" alt="kx diag demo" width="800"/>
+</div>
 
-`kx` maintains a history of up to 10 `kx get` results in `~/.kx/state.json`. A cursor tracks your current position; index-based commands always resolve against the entry at the cursor.
+`kx diag <index>` diagnoses a single resource: a verdict banner, a `SUMMARY`
+of findings (CrashLoopBackOff, image pull failures, OOMKills, unschedulable
+pods, stalled rollouts, missing Service endpoints, Pending PVCs, failed
+CronJob runs, usage near limits), a per-pod status table, recent log tails
+from broken containers, and warning events — one screen instead of four
+kubectl commands.
 
-```
-$ kx get pods          # saves a new entry, cursor advances
-$ kx get deployments   # saves another entry, cursor advances
-$ kx logs 1            # resolves index 1 from the pods result
-$ kx state --all       # lists all history entries and the current position
-```
+### Scan images for vulnerabilities
+
+`kx scan <index>` scans the unique container images of an indexed workload
+(init containers and CronJob job templates included); bare `kx scan` sweeps
+every workload in the namespace. Results come back as a severity summary,
+or the full per-image CVE report with `--full`. Requires
+[Docker Scout](https://docs.docker.com/scout/).
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jzills/kx/main/demo/scan.gif" alt="kx scan demo" width="800"/>
+</div>
+
+## State
 
-Use `kx state <position>` to jump directly to any history entry, and `kx drop <position>` to remove one.
+`kx` maintains a history of up to 10 `kx get` results in `~/.kx/state.json`. A cursor tracks your current position; index-based commands always resolve against the entry at the cursor. `kx state --all` lists the history, `kx state <position>` jumps to an entry, `kx back`/`kx forward` step through it, and `kx drop <position>` removes one.
 
 ## Configuration
 
@@ -194,13 +176,13 @@ Use `kx state <position>` to jump directly to any history entry, and `kx drop <p
 
 Styled output is emitted only when stdout is a terminal — piped or redirected output is plain text, so `kx get pods | grep worker` stays clean. The [`NO_COLOR`](https://no-color.org/) convention is honored as well.
 
-### Themes
+## Themes
 
-```bash
-kx theme        # list available themes (indexed) with a preview of each
-kx theme nord   # persist a theme to ~/.kx/config.toml
-kx theme 3      # same, selecting by index from the kx theme listing
-```
+`kx theme` lists the available themes with a preview of each; `kx theme <name|index>` persists a choice to `~/.kx/config.toml`.
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jzills/kx/main/demo/theme.gif" alt="kx theme demo" width="800"/>
+</div>
 
 Prefab themes: `github-dark` (default), `dracula`, `nord`, `gruvbox`, `solarized-dark`, `catppuccin-mocha`, `tokyo-night`, `rose-pine`, `mono`, `light` (for light terminal backgrounds), and `plain` (no styling at all).
 
@@ -217,3 +199,7 @@ Run the CLI directly:
 ```bash
 python -m kx.main --help
 ```
+
+The demo GIFs are rendered from [VHS](https://github.com/charmbracelet/vhs)
+tapes — see [`demo/README.md`](demo/README.md) for seeding the demo namespace
+and re-recording.

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

@@ -47,7 +47,7 @@ With pip:
 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):
+As a kubectl plugin via [krew](https://krew.sigs.k8s.io/), where kx is published as `idx` (no Python required):
 
 ```bash
 kubectl krew install idx
@@ -65,26 +65,9 @@ pipx run --spec kx-cli kx get pods
 
 ## Usage
 
-### List resources
+`kx get <resource>` fetches resources and assigns each row an index; every other command takes those indexes. Extra flags pass through to kubectl (`-n <namespace>`, selectors, ...), and `--match`/`-m` filters rows by name substring. All-namespace listings (`-A`) are display-only — names aren't unique across namespaces.
 
-```
-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). 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
-Pods · default · 3 items
-  X    NAME                      READY    STATUS     RESTARTS    AGE
-  1    api-7d9f4b8c6-xkp2q       1/1      Running    0            2d
-  2    worker-6c8b5f7d9-mnt4r    1/1      Running    3            5h
-  3    postgres-0                1/1      Running    0           12d
-```
-
-All subsequent commands reference resources by their `X` index from the last `kx get`.
+Known kinds can drop the `get`: `kx pods`, `kx deploy -n kube-system`, `kx svc --match api` — kubectl shorthands (`po`, `deploy`, `svc`, `sts`, ...) included. An integer after a kind relists just that index: `kx po 3`. CRDs and other resource types still use `kx get <resource>`.
 
 Global flags: `--no-color` disables styled output, `-v`/`--version` prints the installed version, and `--help` on any command shows usage, examples, and aliases.
 
@@ -94,10 +77,15 @@ Global flags: `--no-color` disables styled output, `-v`/`--version` prints the i
 | Command | Description |
 |---|---|
 | `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 top [--match/-m str] [--no-limits] [kubectl flags...]` | List CPU/memory usage for pods in the current namespace and assign index numbers, like kx get; shows usage as a percent of each pod's resource limits unless --no-limits. |
 | `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 scan [<index>] [--engine str] [--full] [kubectl flags...]` | Scan the unique container images of an indexed workload for vulnerabilities, or the whole namespace when no index is given; prints a severity summary table by default, or the raw scanner output with --full. |
 | `kx labels <indexes>... [--selector/-s]` | Show labels for one or more indexed resources; --selector formats output as a label selector. |
+| `kx annotations <indexes>...` | Show annotations for one or more indexed resources. |
+| `kx label <index> [<pairs>...] [--remove str] [--overwrite]` | Set or remove labels on an indexed resource. |
+| `kx annotate <index> [<pairs>...] [--remove str] [--overwrite]` | Set or remove annotations on an indexed resource. |
 | `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. |
@@ -106,8 +94,9 @@ Global flags: `--no-color` disables styled output, `-v`/`--version` prints the i
 | `kx rollout <action> <index>` | Run a rollout action (status, restart, pause, resume, history, undo) on a Deployment, StatefulSet, or DaemonSet. |
 | `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 diagnostic [<index>]` | Diagnose an indexed Deployment, StatefulSet, DaemonSet, Job, CronJob, Service, PersistentVolumeClaim, or Pod, or triage the whole namespace when no index is given; alias: kx diag. |
 | `kx namespace [<index>]` | List namespaces, or switch to an indexed one; alias: kx ns. |
+| `kx context [<index>]` | List kubeconfig contexts, or switch to an indexed one; alias: kx contexts. |
 | `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). |
@@ -115,48 +104,41 @@ Global flags: `--no-color` disables styled output, `-v`/`--version` prints the i
 | `kx forward` | Navigate to the next kx get result. |
 <!-- commands-table-end -->
 
-### Example workflow
+### Triage a namespace
 
-```bash
-# list deployments, pick index 2
-kx get deployments
-kx describe 2
-
-# check events on that deployment
-kx events 2
-
-# drill into a pod
-kx get pods
-kx logs 1
-kx exec 1            # opens bash/sh
-kx exec 1 -- env     # run a specific command
-
-# forward local port 8080 to port 80 on a service
-kx get services
-kx port-forward 2 8080:80
-
-# navigate history after multiple gets
-kx get pods
-kx get deployments
-kx logs 1            # logs from pod index 1
-kx state --all       # review full history
-
-# clean up
-kx delete 3
-```
+Bare `kx diag` sweeps the current namespace — Deployments, StatefulSets,
+DaemonSets, Jobs, CronJobs, Services, and PersistentVolumeClaims, plus pods
+nothing owns — and prints a ranked table of what's unhealthy. Findings also
+draw on live resource usage (`kx top`): a pod running hot against its memory
+limit is flagged as an OOMKill risk before it dies. The rows are indexed, so
+`kx diag 1` or `kx logs 2` drill straight in.
 
-## State
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jzills/kx/main/demo/diag.gif" alt="kx diag demo" width="800"/>
+</div>
 
-`kx` maintains a history of up to 10 `kx get` results in `~/.kx/state.json`. A cursor tracks your current position; index-based commands always resolve against the entry at the cursor.
+`kx diag <index>` diagnoses a single resource: a verdict banner, a `SUMMARY`
+of findings (CrashLoopBackOff, image pull failures, OOMKills, unschedulable
+pods, stalled rollouts, missing Service endpoints, Pending PVCs, failed
+CronJob runs, usage near limits), a per-pod status table, recent log tails
+from broken containers, and warning events — one screen instead of four
+kubectl commands.
 
-```
-$ kx get pods          # saves a new entry, cursor advances
-$ kx get deployments   # saves another entry, cursor advances
-$ kx logs 1            # resolves index 1 from the pods result
-$ kx state --all       # lists all history entries and the current position
-```
+### Scan images for vulnerabilities
+
+`kx scan <index>` scans the unique container images of an indexed workload
+(init containers and CronJob job templates included); bare `kx scan` sweeps
+every workload in the namespace. Results come back as a severity summary,
+or the full per-image CVE report with `--full`. Requires
+[Docker Scout](https://docs.docker.com/scout/).
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jzills/kx/main/demo/scan.gif" alt="kx scan demo" width="800"/>
+</div>
+
+## State
 
-Use `kx state <position>` to jump directly to any history entry, and `kx drop <position>` to remove one.
+`kx` maintains a history of up to 10 `kx get` results in `~/.kx/state.json`. A cursor tracks your current position; index-based commands always resolve against the entry at the cursor. `kx state --all` lists the history, `kx state <position>` jumps to an entry, `kx back`/`kx forward` step through it, and `kx drop <position>` removes one.
 
 ## Configuration
 
@@ -171,13 +153,13 @@ Use `kx state <position>` to jump directly to any history entry, and `kx drop <p
 
 Styled output is emitted only when stdout is a terminal — piped or redirected output is plain text, so `kx get pods | grep worker` stays clean. The [`NO_COLOR`](https://no-color.org/) convention is honored as well.
 
-### Themes
+## Themes
 
-```bash
-kx theme        # list available themes (indexed) with a preview of each
-kx theme nord   # persist a theme to ~/.kx/config.toml
-kx theme 3      # same, selecting by index from the kx theme listing
-```
+`kx theme` lists the available themes with a preview of each; `kx theme <name|index>` persists a choice to `~/.kx/config.toml`.
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jzills/kx/main/demo/theme.gif" alt="kx theme demo" width="800"/>
+</div>
 
 Prefab themes: `github-dark` (default), `dracula`, `nord`, `gruvbox`, `solarized-dark`, `catppuccin-mocha`, `tokyo-night`, `rose-pine`, `mono`, `light` (for light terminal backgrounds), and `plain` (no styling at all).
 
@@ -194,3 +176,7 @@ Run the CLI directly:
 ```bash
 python -m kx.main --help
 ```
+
+The demo GIFs are rendered from [VHS](https://github.com/charmbracelet/vhs)
+tapes — see [`demo/README.md`](demo/README.md) for seeding the demo namespace
+and re-recording.

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

@@ -1,6 +1,6 @@
 [project]
 name = "kx-cli"
-version = "0.0.8"
+version = "0.0.10"
 description = "kubectl wrapper with index-based resource selection"
 readme = "README.md"
 requires-python = ">=3.11"

kx_cli-0.0.10/src/kx/commands/_metadata.py

@@ -0,0 +1,16 @@
+import json
+
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import StateServiceProtocol
+
+
+def fetch_metadata_field(
+    kubectl: KubectlServiceProtocol,
+    state: StateServiceProtocol,
+    index: int,
+    field: str,
+) -> dict[str, str]:
+    name, namespace, kind = state.fields(index)
+    raw = kubectl.run(["get", kind, name, "-n", namespace, "-o", "json"])
+    obj = json.loads(raw)
+    return obj.get("metadata", {}).get(field) or {}

kx_cli-0.0.10/src/kx/commands/annotations.py

@@ -0,0 +1,12 @@
+from kx.commands._metadata import fetch_metadata_field
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import StateServiceProtocol
+
+
+class AnnotationsCommand:
+    def __init__(self, state: StateServiceProtocol, kubectl: KubectlServiceProtocol):
+        self.state = state
+        self.kubectl = kubectl
+
+    def execute(self, index: int) -> dict[str, str]:
+        return fetch_metadata_field(self.kubectl, self.state, index, "annotations")

kx_cli-0.0.10/src/kx/commands/context.py

@@ -0,0 +1,13 @@
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import StateServiceProtocol
+
+
+class ContextCommand:
+    def __init__(self, state: StateServiceProtocol, kubectl: KubectlServiceProtocol):
+        self.state = state
+        self.kubectl = kubectl
+
+    def execute(self, index: int) -> str:
+        name, _, _ = self.state.fields(index)
+        self.kubectl.run(["config", "use-context", name])
+        return name

kx_cli-0.0.10/src/kx/commands/contexts.py

@@ -0,0 +1,28 @@
+from kx.index import IndexServiceProtocol
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import State, StateServiceProtocol
+
+
+class ContextsCommand:
+    def __init__(
+        self,
+        kubectl: KubectlServiceProtocol,
+        state: StateServiceProtocol,
+        index: IndexServiceProtocol,
+    ):
+        self.kubectl = kubectl
+        self.state = state
+        self.index = index
+
+    def execute(self) -> str:
+        output = self.kubectl.run(["config", "get-contexts"])
+        indexed_output, names = self.index.add(output)
+        if names:
+            current = self.kubectl.current_context()
+            self.state.save(
+                State(
+                    resources={name: "Context" for name in names},
+                    namespace=current,
+                )
+            )
+        return indexed_output