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

kx_cli-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Alexander Zillwood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kx_cli-0.0.3/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: kx-cli
+Version: 0.0.3
+Summary: kubectl wrapper with index-based resource selection
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer==0.25.1
+Requires-Dist: click
+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">
+
+```
+██╗  ██╗██╗  ██╗
+██║ ██╔╝╚██╗██╔╝
+█████╔╝  ╚███╔╝ 
+██╔═██╗  ██╔██╗ 
+██║  ██╗██╔╝ ██╗
+╚═╝  ╚═╝╚═╝  ╚═╝
+```
+
+**kubectl, indexed.**
+
+</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.
+
+## 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
+
+| Command | Description |
+|---|---|
+| `kx get <resource> [--match\|-m <str>] [kubectl flags...]` | List resources with index numbers; optionally filter by name substring |
+| `kx describe <index> [kubectl flags...]` | Show `kubectl describe` output for an indexed resource |
+| `kx events <index>` | Show Kubernetes events for the resource |
+| `kx logs <index> [kubectl flags...]` | Stream logs; aggregates across pods for Deployments, StatefulSets, DaemonSets, and Services |
+| `kx yaml <index>` | Print the raw YAML manifest |
+| `kx exec <index> [cmd] [kubectl flags...]` | Open an interactive shell in a pod (bash → sh fallback); pass a custom command with `cmd` |
+| `kx edit <index> [kubectl flags...]` | Open the resource in your editor via `kubectl edit` |
+| `kx delete <index> [-y]` | Delete the resource (prompts for confirmation; `-y` skips it) |
+| `kx tree <index> [--index\|-i]` | Show the ownership graph for a resource; `--index` assigns indexes to tree nodes |
+| `kx port-forward <index> <port> [kubectl flags...]` | Forward a local port to a resource (supports Pod, Deployment, ReplicaSet, StatefulSet, DaemonSet, Service) |
+| `kx state` | Show the current state (namespace and indexed resources from the last `kx get`) |
+
+### 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
+
+# clean up
+kx delete 3
+```
+
+## State
+
+`kx` saves the last `get` result to `~/.kx_state.json`. Index-based commands read from this file, so switching namespaces or resource types requires a new `kx get`.
+
+## 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/README.md

@@ -0,0 +1,100 @@
+<div align="center">
+
+```
+██╗  ██╗██╗  ██╗
+██║ ██╔╝╚██╗██╔╝
+█████╔╝  ╚███╔╝ 
+██╔═██╗  ██╔██╗ 
+██║  ██╗██╔╝ ██╗
+╚═╝  ╚═╝╚═╝  ╚═╝
+```
+
+**kubectl, indexed.**
+
+</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.
+
+## 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
+
+| Command | Description |
+|---|---|
+| `kx get <resource> [--match\|-m <str>] [kubectl flags...]` | List resources with index numbers; optionally filter by name substring |
+| `kx describe <index> [kubectl flags...]` | Show `kubectl describe` output for an indexed resource |
+| `kx events <index>` | Show Kubernetes events for the resource |
+| `kx logs <index> [kubectl flags...]` | Stream logs; aggregates across pods for Deployments, StatefulSets, DaemonSets, and Services |
+| `kx yaml <index>` | Print the raw YAML manifest |
+| `kx exec <index> [cmd] [kubectl flags...]` | Open an interactive shell in a pod (bash → sh fallback); pass a custom command with `cmd` |
+| `kx edit <index> [kubectl flags...]` | Open the resource in your editor via `kubectl edit` |
+| `kx delete <index> [-y]` | Delete the resource (prompts for confirmation; `-y` skips it) |
+| `kx tree <index> [--index\|-i]` | Show the ownership graph for a resource; `--index` assigns indexes to tree nodes |
+| `kx port-forward <index> <port> [kubectl flags...]` | Forward a local port to a resource (supports Pod, Deployment, ReplicaSet, StatefulSet, DaemonSet, Service) |
+| `kx state` | Show the current state (namespace and indexed resources from the last `kx get`) |
+
+### 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
+
+# clean up
+kx delete 3
+```
+
+## State
+
+`kx` saves the last `get` result to `~/.kx_state.json`. Index-based commands read from this file, so switching namespaces or resource types requires a new `kx get`.
+
+## 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/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "kx-cli"
+version = "0.0.3"
+description = "kubectl wrapper with index-based resource selection"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "typer==0.25.1",
+    "click",
+    "kubernetes",
+    "rich",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff",
+    "pre-commit",
+    "pytest",
+]
+
+[project.scripts]
+kx = "kx.main:app"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

kx_cli-0.0.3/src/kx/commands/delete.py

@@ -0,0 +1,22 @@
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import StateServiceProtocol
+from kx.types import Confirm
+
+
+class DeleteCommand:
+    def __init__(
+        self,
+        state: StateServiceProtocol,
+        kubectl: KubectlServiceProtocol,
+        confirm: Confirm,
+    ):
+        self.state = state
+        self.kubectl = kubectl
+        self.confirm = confirm
+
+    def execute(self, index: int, yes: bool) -> str:
+        name, namespace, kind = self.state.fields(index)
+        if not yes:
+            self.confirm(f"Delete {kind}/{name} in {namespace}?")
+        self.kubectl.run(["delete", kind, name, "-n", namespace])
+        return f"Deleted {kind}/{name}"

kx_cli-0.0.3/src/kx/commands/describe.py

@@ -0,0 +1,18 @@
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import StateServiceProtocol
+
+
+class DescribeCommand:
+    def __init__(
+        self,
+        state: StateServiceProtocol,
+        kubectl: KubectlServiceProtocol,
+    ):
+        self.state = state
+        self.kubectl = kubectl
+
+    def execute(self, index: int, extra_args: list[str] = []) -> None:
+        name, namespace, kind = self.state.fields(index)
+        self.kubectl.run_interactive(
+            ["describe", kind, name, "-n", namespace, *extra_args]
+        )

kx_cli-0.0.3/src/kx/commands/edit.py

@@ -0,0 +1,12 @@
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import StateServiceProtocol
+
+
+class EditCommand:
+    def __init__(self, state: StateServiceProtocol, kubectl: KubectlServiceProtocol):
+        self.state = state
+        self.kubectl = kubectl
+
+    def execute(self, index: int, extra_args: list[str] = []) -> None:
+        name, namespace, kind = self.state.fields(index)
+        self.kubectl.run_interactive(["edit", kind, name, "-n", namespace, *extra_args])

kx_cli-0.0.3/src/kx/commands/events.py

@@ -0,0 +1,26 @@
+from kx.events import EventsServiceProtocol
+from kx.state import StateServiceProtocol
+
+
+class EventsCommand:
+    def __init__(self, state: StateServiceProtocol, events: EventsServiceProtocol):
+        self.state = state
+        self.events = events
+
+    def execute(self, index: int) -> str:
+        name, namespace, kind = self.state.fields(index)
+        all_events = self.events.get(namespace)
+        filtered = self.events.filter(all_events, name, kind)
+
+        if not filtered:
+            return "No events found"
+
+        output = []
+        for event in filtered:
+            obj = event.involved_object
+            output.append(
+                f"{event.type:8} {event.reason:30} "
+                f"{obj.kind:10} {event.metadata.creation_timestamp} "
+                f"{event.message}"
+            )
+        return "\n".join(output)

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

@@ -0,0 +1,28 @@
+from kx.kinds import Kind
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import StateServiceProtocol
+
+
+class ExecCommand:
+    def __init__(self, state: StateServiceProtocol, kubectl: KubectlServiceProtocol):
+        self.state = state
+        self.kubectl = kubectl
+
+    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:
+            self.kubectl.run_interactive(
+                ["exec", "-it", name, "-n", namespace, *extra_args, "--", *cmd]
+            )
+        else:
+            rc = self.kubectl.run_interactive(
+                ["exec", "-it", name, "-n", namespace, *extra_args, "--", "bash"]
+            )
+            if rc != 0:
+                self.kubectl.run_interactive(
+                    ["exec", "-it", name, "-n", namespace, *extra_args, "--", "sh"]
+                )

kx_cli-0.0.3/src/kx/commands/get.py

@@ -0,0 +1,46 @@
+from kx.index import IndexServiceProtocol
+from kx.kinds import normalize_kind
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import State, StateServiceProtocol
+
+
+def _extract_namespace(extra_args: list[str]) -> str | None:
+    for index, arg in enumerate(extra_args):
+        if arg in ("-n", "--namespace") and index + 1 < len(extra_args):
+            return extra_args[index + 1]
+        if arg.startswith("--namespace="):
+            return arg.split("=", 1)[1]
+    return None
+
+
+class GetCommand:
+    def __init__(
+        self,
+        kubectl: KubectlServiceProtocol,
+        state: StateServiceProtocol,
+        index: IndexServiceProtocol,
+    ):
+        self.kubectl = kubectl
+        self.state = state
+        self.index = index
+
+    def execute(
+        self,
+        resource: str,
+        filter_term: str | None = None,
+        extra_args: list[str] = [],
+    ) -> str:
+        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:
+            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)
+            )
+        return indexed_output

kx_cli-0.0.3/src/kx/commands/logs.py

@@ -0,0 +1,42 @@
+import json
+
+from kx.kinds import Kind
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import StateServiceProtocol
+
+_AGGREGATE_KINDS = {Kind.Deployment, Kind.StatefulSet, Kind.DaemonSet, Kind.Service}
+
+
+class LogsCommand:
+    def __init__(self, state: StateServiceProtocol, kubectl: KubectlServiceProtocol):
+        self.state = state
+        self.kubectl = kubectl
+
+    def execute(self, index: int, extra_args: list[str] = []) -> None:
+        name, namespace, kind = self.state.fields(index)
+        if kind == Kind.Pod:
+            self.kubectl.run_interactive(["logs", name, "-n", namespace, *extra_args])
+        elif kind in _AGGREGATE_KINDS:
+            selector = self._selector(name, namespace, kind)
+            self.kubectl.run_interactive(
+                ["logs", "-l", selector, "--prefix=true", "-n", namespace, *extra_args]
+            )
+        else:
+            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"])
+        obj = json.loads(raw)
+        labels = self._extract_labels(obj, kind)
+        if not labels:
+            raise ValueError(
+                f"{kind}/{name} has no pod selector; cannot aggregate logs."
+            )
+        return ",".join(f"{k}={v}" for k, v in labels.items())
+
+    @staticmethod
+    def _extract_labels(obj: dict, kind: str) -> dict:
+        spec = obj.get("spec", {})
+        if kind == Kind.Service:
+            return spec.get("selector") or {}
+        return (spec.get("selector") or {}).get("matchLabels") or {}

kx_cli-0.0.3/src/kx/commands/port_forward.py

@@ -0,0 +1,26 @@
+from kx.kinds import Kind
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import StateServiceProtocol
+
+_SUPPORTED_KINDS = {
+    Kind.Pod,
+    Kind.Deployment,
+    Kind.ReplicaSet,
+    Kind.StatefulSet,
+    Kind.DaemonSet,
+    Kind.Service,
+}
+
+
+class PortForwardCommand:
+    def __init__(self, kubectl: KubectlServiceProtocol, state: StateServiceProtocol):
+        self.kubectl = kubectl
+        self.state = state
+
+    def execute(self, index: int, port: str, extra_args: list[str] = []) -> None:
+        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(
+            ["port-forward", f"{kind}/{name}", port, "-n", namespace, *extra_args]
+        )

kx_cli-0.0.3/src/kx/commands/state.py

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

kx_cli-0.0.3/src/kx/commands/tree.py

@@ -0,0 +1,34 @@
+from rich.tree import Tree
+
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import State, StateServiceProtocol
+from kx.types import BuildIndexedTree, BuildTree
+
+
+class TreeCommand:
+    def __init__(
+        self,
+        state: StateServiceProtocol,
+        kubectl: KubectlServiceProtocol,
+        build_tree: BuildTree,
+        build_indexed_tree: BuildIndexedTree,
+    ):
+        self.state = state
+        self.kubectl = kubectl
+        self.build_tree = build_tree
+        self.build_indexed_tree = build_indexed_tree
+
+    def execute(self, index: int, indexed: bool = False) -> Tree:
+        name, namespace, kind = self.state.fields(index)
+        if indexed:
+            tree, resources = self.build_indexed_tree(kind, name, namespace)
+            if resources:
+                self.state.save(
+                    State(
+                        resources={name: kind for name, kind in resources},
+                        namespace=namespace,
+                    )
+                )
+        else:
+            tree = self.build_tree(kind, name, namespace)
+        return tree

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

@@ -0,0 +1,12 @@
+from kx.kubectl import KubectlServiceProtocol
+from kx.state import StateServiceProtocol
+
+
+class YamlCommand:
+    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"])