kx-cli 0.0.3__tar.gz → 0.0.5__tar.gz

kx_cli-0.0.5/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: kx-cli
+Version: 0.0.5
+Summary: kubectl wrapper with index-based resource selection
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+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: kubernetes
+Requires-Dist: rich
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jzills/kx/main/assets/banner.svg" alt="kx — kubectl, indexed." width="800"/>
+</div>
+
+<br>
+
+<div align="center">
+
+# kubectl, indexed
+
+</div>
+
+<div align="center">
+
+[![PyPI version](https://img.shields.io/pypi/v/kx-cli?style=flat-square&color=3fb950&labelColor=21262d)](https://pypi.org/project/kx-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/kx-cli?style=flat-square&color=3fb950&labelColor=21262d)](https://pypi.org/project/kx-cli/)
+[![License](https://img.shields.io/github/license/jzills/kx?style=flat-square&color=3fb950&labelColor=21262d)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/jzills/kx/pr.yml?style=flat-square&color=3fb950&labelColor=21262d&label=CI)](https://github.com/jzills/kx/actions/workflows/pr.yml)
+
+</div>
+
+`kx` is a kubectl wrapper that adds index-based resource selection. Run `kx get <resource>` once, then reference any result by number instead of typing full resource names.
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jzills/kx/main/demo/demo.gif" alt="kx demo" width="800"/>
+</div>
+
+## Install
+
+```bash
+pip install kx-cli
+```
+
+## Usage
+
+### List resources
+
+```
+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).
+
+```
+$ kx get pods
+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`.
+
+### 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 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 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). |
+| `kx tree <index> [--index/-i]` | Show the ownership graph for an indexed resource; --index assigns indexes to tree nodes. |
+| `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 namespace <index>` | Switch to an indexed namespace; alias: kx ns (run kx get namespaces first). |
+| `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 back` | Navigate to the previous kx get result. |
+| `kx forward` | Navigate to the next kx get result. |
+<!-- commands-table-end -->
+
+### Example workflow
+
+```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
+```
+
+## State
+
+`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 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
+```
+
+Use `kx state <position>` to jump directly to any history entry, and `kx drop <position>` to remove one.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Run the CLI directly:
+
+```bash
+python -m kx.main --help
+```

kx_cli-0.0.5/README.md

@@ -0,0 +1,134 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jzills/kx/main/assets/banner.svg" alt="kx — kubectl, indexed." width="800"/>
+</div>
+
+<br>
+
+<div align="center">
+
+# kubectl, indexed
+
+</div>
+
+<div align="center">
+
+[![PyPI version](https://img.shields.io/pypi/v/kx-cli?style=flat-square&color=3fb950&labelColor=21262d)](https://pypi.org/project/kx-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/kx-cli?style=flat-square&color=3fb950&labelColor=21262d)](https://pypi.org/project/kx-cli/)
+[![License](https://img.shields.io/github/license/jzills/kx?style=flat-square&color=3fb950&labelColor=21262d)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/jzills/kx/pr.yml?style=flat-square&color=3fb950&labelColor=21262d&label=CI)](https://github.com/jzills/kx/actions/workflows/pr.yml)
+
+</div>
+
+`kx` is a kubectl wrapper that adds index-based resource selection. Run `kx get <resource>` once, then reference any result by number instead of typing full resource names.
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jzills/kx/main/demo/demo.gif" alt="kx demo" width="800"/>
+</div>
+
+## Install
+
+```bash
+pip install kx-cli
+```
+
+## Usage
+
+### List resources
+
+```
+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).
+
+```
+$ kx get pods
+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`.
+
+### 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 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 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). |
+| `kx tree <index> [--index/-i]` | Show the ownership graph for an indexed resource; --index assigns indexes to tree nodes. |
+| `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 namespace <index>` | Switch to an indexed namespace; alias: kx ns (run kx get namespaces first). |
+| `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 back` | Navigate to the previous kx get result. |
+| `kx forward` | Navigate to the next kx get result. |
+<!-- commands-table-end -->
+
+### Example workflow
+
+```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
+```
+
+## State
+
+`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 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
+```
+
+Use `kx state <position>` to jump directly to any history entry, and `kx drop <position>` to remove one.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Run the CLI directly:
+
+```bash
+python -m kx.main --help
+```

{kx_cli-0.0.3 → kx_cli-0.0.5}/pyproject.toml

@@ -1,12 +1,17 @@
 [project]
 name = "kx-cli"
-version = "0.0.3"
+version = "0.0.5"
 description = "kubectl wrapper with index-based resource selection"
 readme = "README.md"
 requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
 dependencies = [
-    "typer==0.25.1",
-    "click",
+    "typer==0.26.8",
     "kubernetes",
     "rich",
 ]

kx_cli-0.0.5/src/kx/commands/back.py

@@ -0,0 +1,13 @@
+from dataclasses import asdict
+import json
+
+from kx.state import StateServiceProtocol
+
+
+class BackCommand:
+    def __init__(self, state: StateServiceProtocol):
+        self.state = state
+
+    def execute(self) -> str:
+        state = self.state.navigate(-1)
+        return json.dumps(asdict(state), indent=2)

kx_cli-0.0.5/src/kx/commands/drop.py

@@ -0,0 +1,9 @@
+from kx.state import StateHistory, StateServiceProtocol
+
+
+class DropCommand:
+    def __init__(self, state: StateServiceProtocol):
+        self.state = state
+
+    def execute(self, position: int) -> StateHistory:
+        return self.state.drop(position)

kx_cli-0.0.5/src/kx/commands/exec.py

@@ -0,0 +1,54 @@
+import subprocess
+
+from kx.kinds import Kind
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import StateServiceProtocol
+
+
+class ExecCommand:
+    def __init__(
+        self,
+        state: StateServiceProtocol,
+        kubectl: KubectlServiceProtocol,
+        shells: tuple[str, ...] = ("bash", "sh"),
+    ):
+        self.state = state
+        self.kubectl = kubectl
+        self.shells = shells
+
+    def execute(
+        self, index: int, cmd: list[str] | None, extra_args: list[str] = []
+    ) -> None:
+        name, namespace, kind = self.state.fields(index)
+        if kind != Kind.Pod:
+            raise ValueError("exec is only supported for pods.")
+        if cmd:
+            rc = self.kubectl.run_interactive(
+                ["exec", "-it", name, "-n", namespace, *extra_args, "--", *cmd],
+                stderr=subprocess.DEVNULL,
+            )
+            if rc != 0:
+                raise ValueError(f"Command failed in container (exit {rc}).")
+        else:
+            for shell in self.shells:
+                probe_rc = self.kubectl.probe(
+                    [
+                        "exec",
+                        name,
+                        "-n",
+                        namespace,
+                        *extra_args,
+                        "--",
+                        shell,
+                        "-c",
+                        "exit 0",
+                    ]
+                )
+                if probe_rc == 0:
+                    self.kubectl.run_interactive(
+                        ["exec", "-it", name, "-n", namespace, *extra_args, "--", shell]
+                    )
+                    return
+            raise ValueError(
+                "No shell found in container. Provide an explicit command: kx exec <index> -- /path/to/binary"
+            )

kx_cli-0.0.5/src/kx/commands/forward.py

@@ -0,0 +1,13 @@
+from dataclasses import asdict
+import json
+
+from kx.state import StateServiceProtocol
+
+
+class ForwardCommand:
+    def __init__(self, state: StateServiceProtocol):
+        self.state = state
+
+    def execute(self) -> str:
+        state = self.state.navigate(+1)
+        return json.dumps(asdict(state), indent=2)

kx_cli-0.0.5/src/kx/commands/labels.py

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

kx_cli-0.0.3/src/kx/commands/yaml.py → kx_cli-0.0.5/src/kx/commands/namespace.py

@@ -2,11 +2,12 @@ from kx.kubectl import KubectlServiceProtocol
 from kx.state import StateServiceProtocol
 
 
-class YamlCommand:
+class NamespaceCommand:
     def __init__(self, state: StateServiceProtocol, kubectl: KubectlServiceProtocol):
         self.state = state
         self.kubectl = kubectl
 
     def execute(self, index: int) -> str:
-        name, namespace, kind = self.state.fields(index)
-        return self.kubectl.run(["get", kind, name, "-n", namespace, "-o", "yaml"])
+        name, _, _ = self.state.fields(index)
+        self.kubectl.run(["config", "set-context", "--current", f"--namespace={name}"])
+        return name

kx_cli-0.0.5/src/kx/commands/rollout.py

@@ -0,0 +1,35 @@
+from enum import Enum
+
+from kx.kinds import Kind
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import StateServiceProtocol
+
+_SUPPORTED_KINDS = {Kind.Deployment, Kind.StatefulSet, Kind.DaemonSet}
+_INTERACTIVE_ACTIONS = {"status"}
+
+
+class RolloutAction(str, Enum):
+    status = "status"
+    restart = "restart"
+    pause = "pause"
+    resume = "resume"
+    history = "history"
+    undo = "undo"
+
+
+class RolloutCommand:
+    def __init__(self, kubectl: KubectlServiceProtocol, state: StateServiceProtocol):
+        self.kubectl = kubectl
+        self.state = state
+
+    def execute(
+        self, index: int, action: RolloutAction = RolloutAction.status
+    ) -> str | None:
+        name, namespace, kind = self.state.fields(index)
+        if kind not in _SUPPORTED_KINDS:
+            raise ValueError(f"rollout is not supported for '{kind}'.")
+        args = ["rollout", action.value, f"{kind}/{name}", "-n", namespace]
+        if action.value in _INTERACTIVE_ACTIONS:
+            self.kubectl.run_interactive(args)
+            return None
+        return self.kubectl.run(args)

kx_cli-0.0.5/src/kx/commands/scale.py

@@ -0,0 +1,21 @@
+from kx.kinds import Kind
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import StateServiceProtocol
+
+_SUPPORTED_KINDS = {Kind.Deployment, Kind.StatefulSet, Kind.ReplicaSet}
+
+
+class ScaleCommand:
+    def __init__(self, kubectl: KubectlServiceProtocol, state: StateServiceProtocol):
+        self.kubectl = kubectl
+        self.state = state
+
+    def execute(self, index: int, replicas: int) -> str:
+        name, namespace, kind = self.state.fields(index)
+        if kind not in _SUPPORTED_KINDS:
+            raise ValueError(f"scale is not supported for '{kind}'.")
+        self.kubectl.run(
+            ["scale", f"{kind}/{name}", f"--replicas={replicas}", "-n", namespace]
+        )
+        noun = "replica" if replicas == 1 else "replicas"
+        return f"Scaled {kind}/{name} to {replicas} {noun}"

kx_cli-0.0.5/src/kx/commands/yaml.py

@@ -0,0 +1,32 @@
+import yaml
+
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import StateServiceProtocol
+
+
+def _find_keys(data: dict | list, keys: set[str]) -> dict:
+    result = {}
+    if isinstance(data, dict):
+        for k, v in data.items():
+            if k in keys:
+                result[k] = v
+            else:
+                result.update(_find_keys(v, keys))
+    elif isinstance(data, list):
+        for item in data:
+            result.update(_find_keys(item, keys))
+    return result
+
+
+class YamlCommand:
+    def __init__(self, state: StateServiceProtocol, kubectl: KubectlServiceProtocol):
+        self.state = state
+        self.kubectl = kubectl
+
+    def execute(self, index: int, show: list[str] | None = None) -> str:
+        name, namespace, kind = self.state.fields(index)
+        raw = self.kubectl.run(["get", kind, name, "-n", namespace, "-o", "yaml"])
+        if not show:
+            return raw
+        data = yaml.safe_load(raw)
+        return yaml.dump(_find_keys(data, set(show)), default_flow_style=False)

kx_cli-0.0.5/src/kx/config.py

@@ -0,0 +1,38 @@
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+_CONFIG_FILE = Path.home() / ".kx" / "config.toml"
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    max_history: int = 10
+    shells: tuple[str, ...] = ("bash", "sh")
+
+
+def load_config() -> Config:
+    kwargs: dict = {}
+
+    if _CONFIG_FILE.exists():
+        try:
+            with open(_CONFIG_FILE, "rb") as f:
+                data = tomllib.load(f)
+        except tomllib.TOMLDecodeError as e:
+            raise SystemExit(f"kx: error reading {_CONFIG_FILE}: {e}")
+        if "max_history" in data:
+            kwargs["max_history"] = data["max_history"]
+        if "shells" in data:
+            kwargs["shells"] = tuple(data["shells"])
+
+    if "KX_MAX_HISTORY" in os.environ:
+        try:
+            kwargs["max_history"] = int(os.environ["KX_MAX_HISTORY"])
+        except ValueError:
+            raise SystemExit("kx: KX_MAX_HISTORY must be an integer")
+
+    if "KX_SHELLS" in os.environ:
+        kwargs["shells"] = tuple(os.environ["KX_SHELLS"].split(","))
+
+    return Config(**kwargs)