kx-cli 0.0.4__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.4 → kx_cli-0.0.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kx-cli"
-version = "0.0.4"
+version = "0.0.5"
 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.7",
+    "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.4 → kx_cli-0.0.5}/src/kx/commands/exec.py

@@ -4,13 +4,17 @@ from kx.kinds import Kind
 from kx.kubectl import KubectlServiceProtocol
 from kx.state import StateServiceProtocol
 
-_SHELLS = ["bash", "sh"]
-
 
 class ExecCommand:
-    def __init__(self, state: StateServiceProtocol, kubectl: KubectlServiceProtocol):
+    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] = []
@@ -26,7 +30,7 @@ class ExecCommand:
             if rc != 0:
                 raise ValueError(f"Command failed in container (exit {rc}).")
         else:
-            for shell in _SHELLS:
+            for shell in self.shells:
                 probe_rc = self.kubectl.probe(
                     [
                         "exec",

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.4 → kx_cli-0.0.5}/src/kx/commands/rollout.py

@@ -5,11 +5,16 @@ 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:
@@ -17,14 +22,14 @@ class RolloutCommand:
         self.kubectl = kubectl
         self.state = state
 
-    def execute(self, index: int, restart: bool = False) -> str | None:
+    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}'.")
-        if restart:
-            self.kubectl.run(["rollout", "restart", f"{kind}/{name}", "-n", namespace])
-            return f"Restarted {kind}/{name}"
-        self.kubectl.run_interactive(
-            ["rollout", "status", f"{kind}/{name}", "-n", namespace]
-        )
-        return None
+        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/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)

{kx_cli-0.0.4 → kx_cli-0.0.5}/src/kx/console.py

@@ -5,6 +5,7 @@ from rich.console import Console
 from rich.table import Table
 
 from kx.kinds import plural_display
+from kx.state import StateHistory
 
 COLOR_HEADER = "#3fb950"
 COLOR_DIM = "#7d8590"
@@ -262,7 +263,7 @@ _KX_ART = [
 def print_help(commands: list[tuple[str, str]]) -> None:
     _console.print()
     for line in _KX_ART:
-        _console.print(f"[bold {COLOR_HEADER}]{line}[/bold {COLOR_HEADER}]")
+        _console.print(line, style=COLOR_HEADER, markup=False, highlight=False)
     _console.print(f"[{COLOR_DIM}]kubectl, indexed.[/{COLOR_DIM}]")
     _console.print()
     _console.rule(style=COLOR_DIM)
@@ -287,6 +288,42 @@ def print_help(commands: list[tuple[str, str]]) -> None:
     )
 
 
+def render_state_history(history: StateHistory) -> None:
+    total = len(history.states)
+    label = "entry" if total == 1 else "entries"
+    _console.print(f"[{COLOR_DIM}]History · {total} {label}[/{COLOR_DIM}]")
+    table = Table(
+        show_header=True,
+        header_style=f"bold {COLOR_HEADER}",
+        box=None,
+        padding=(0, 2),
+    )
+    table.add_column("X", justify="right")
+    table.add_column("")
+    table.add_column("KIND")
+    table.add_column("NAMESPACE")
+    table.add_column("ITEMS", justify="right")
+    for position, state in enumerate(history.states, start=1):
+        is_current = (position - 1) == history.cursor
+        marker = f"[bold {COLOR_HEADER}]→[/bold {COLOR_HEADER}]" if is_current else ""
+        unique_kinds = set(state.resources.values())
+        kind_label = (
+            plural_display(next(iter(unique_kinds)))
+            if len(unique_kinds) == 1
+            else "Mixed"
+        )
+        count = len(state.resources)
+        row_color = COLOR_BODY if is_current else COLOR_DIM
+        table.add_row(
+            f"[{row_color}]{position}[/{row_color}]",
+            marker,
+            f"[{row_color}]{kind_label}[/{row_color}]",
+            f"[{row_color}]{state.namespace}[/{row_color}]",
+            f"[{row_color}]{count}[/{row_color}]",
+        )
+    _console.print(table)
+
+
 def render_labels(labels: dict[str, str]) -> None:
     if not labels:
         _console.print(f"[{COLOR_DIM}]No labels.[/{COLOR_DIM}]")