kx-cli 0.1.0__py3-none-win_arm64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
Binary file
|
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: kx-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: kubectl wrapper with index-based resource selection
|
|
5
|
+
Description-Content-Type: text/markdown
|
|
6
|
+
|
|
7
|
+
<div align="center">
|
|
8
|
+
<img src="https://raw.githubusercontent.com/jzills/kx/main/assets/banner.svg" alt="kx — kubectl, indexed." width="800"/>
|
|
9
|
+
</div>
|
|
10
|
+
|
|
11
|
+
<br>
|
|
12
|
+
|
|
13
|
+
<div align="center">
|
|
14
|
+
|
|
15
|
+
# kubectl, indexed
|
|
16
|
+
|
|
17
|
+
</div>
|
|
18
|
+
|
|
19
|
+
<div align="center">
|
|
20
|
+
|
|
21
|
+
[](https://pypi.org/project/kx-cli/)
|
|
22
|
+
[](LICENSE)
|
|
23
|
+
[](https://github.com/jzills/kx/actions/workflows/pr.yml)
|
|
24
|
+
|
|
25
|
+
</div>
|
|
26
|
+
|
|
27
|
+
`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.
|
|
28
|
+
|
|
29
|
+
<div align="center">
|
|
30
|
+
<img src="https://raw.githubusercontent.com/jzills/kx/main/demo/demo.gif" alt="kx demo" width="800"/>
|
|
31
|
+
</div>
|
|
32
|
+
|
|
33
|
+
## Install
|
|
34
|
+
|
|
35
|
+
Requires `kubectl` on your PATH. Every install path below delivers the same
|
|
36
|
+
prebuilt binary — no Python runtime, no dependencies.
|
|
37
|
+
|
|
38
|
+
With [uv](https://docs.astral.sh/uv/) (recommended):
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
uv tool install kx-cli
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
With [pipx](https://pipx.pypa.io/):
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
pipx install kx-cli
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
With pip:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
pip install kx-cli
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
As a kubectl plugin via [krew](https://krew.sigs.k8s.io/), where kx is published as `idx`:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
kubectl krew install idx
|
|
60
|
+
alias kx="kubectl idx"
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Standalone binaries for linux, macOS and Windows (amd64/arm64) are attached to each [GitHub Release](https://github.com/jzills/kx/releases), with checksums in `SHA256SUMS`.
|
|
64
|
+
|
|
65
|
+
On macOS, the first run of a freshly installed krew plugin or standalone binary takes a few seconds while Gatekeeper scans the binary; later runs are unaffected until the next install. Get it over with up front:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
kx --version >/dev/null
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Or try it without installing (the package is `kx-cli`, the command is `kx`):
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
uvx --from kx-cli kx get pods
|
|
75
|
+
pipx run --spec kx-cli kx get pods
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Usage
|
|
79
|
+
|
|
80
|
+
`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.
|
|
81
|
+
|
|
82
|
+
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>`.
|
|
83
|
+
|
|
84
|
+
Global flags: `--no-color` disables styled output, `-v`/`--version` prints the installed version, and `-h`/`--help` on any command shows usage, examples, and aliases.
|
|
85
|
+
|
|
86
|
+
### Commands
|
|
87
|
+
|
|
88
|
+
<!-- commands-table-start -->
|
|
89
|
+
| Command | Description |
|
|
90
|
+
|---|---|
|
|
91
|
+
| `kx get <resource> [--decode] [--key/-k str] [--match/-m str] [--yes/-y] [kubectl flags...]` | List resources and assign index numbers for use with other commands; shorthand: kx <kind> (e.g. kx pods, kx po 3). |
|
|
92
|
+
| `kx secret [<index>...] [--decode] [--key/-k str] [--match/-m str] [--yes/-y] [kubectl flags...]` | List Secrets like kx get, or show an indexed Secret's data with --decode; alias: kx secrets. |
|
|
93
|
+
| `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. |
|
|
94
|
+
| `kx describe <index>... [kubectl flags...]` | Show full kubectl describe output for one or more indexed resources. |
|
|
95
|
+
| `kx events <index>...` | Show Kubernetes events for one or more indexed resources. |
|
|
96
|
+
| `kx logs <index>... [kubectl flags...]` | Stream logs for an indexed resource; aggregates across pods for Deployments, StatefulSets, DaemonSets, and Services. |
|
|
97
|
+
| `kx labels <index>... [--selector/-s]` | Show labels for one or more indexed resources; --selector formats output as a label selector. |
|
|
98
|
+
| `kx annotations <index>...` | Show annotations for one or more indexed resources. |
|
|
99
|
+
| `kx label <index> [<key=value>...] [--overwrite] [--remove str]` | Set or remove labels on an indexed resource. |
|
|
100
|
+
| `kx annotate <index> [<key=value>...] [--overwrite] [--remove str]` | Set or remove annotations on an indexed resource. |
|
|
101
|
+
| `kx yaml <index>... [--show str]` | Print the raw YAML manifest for one or more indexed resources; --show filters to specific top-level fields. |
|
|
102
|
+
| `kx delete <index>... [--yes/-y]` | Delete one or more indexed resources (prompts for confirmation unless --yes). |
|
|
103
|
+
| `kx edit <index> [kubectl flags...]` | Open an indexed resource in your editor via kubectl edit. |
|
|
104
|
+
| `kx exec <index> [<command>...] [kubectl flags...]` | Open an interactive shell in an indexed pod (bash, falling back to sh). |
|
|
105
|
+
| `kx tree [<index>] [--index/-i]` | Show the ownership graph for an indexed resource, or the whole current namespace when no index is given; --index assigns indexes to tree nodes. A Namespace index graphs that namespace. |
|
|
106
|
+
| `kx rollout <action> <index>` | Run a rollout action (status, restart, pause, resume, history, undo) on a Deployment, StatefulSet, or DaemonSet. |
|
|
107
|
+
| `kx scale <index> <replicas>` | Scale an indexed Deployment, StatefulSet, or ReplicaSet to a given replica count. |
|
|
108
|
+
| `kx scan [<index>] [--engine str] [--full] [scanner 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. Requires the Docker Scout CLI plugin (https://docs.docker.com/scout/). |
|
|
109
|
+
| `kx port-forward <index> <port> [kubectl flags...]` | Forward a local port to an indexed resource (Pod, Deployment, ReplicaSet, StatefulSet, DaemonSet, Service). |
|
|
110
|
+
| `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. |
|
|
111
|
+
| `kx namespace [<index>]` | List namespaces, or switch to an indexed one; alias: kx ns. |
|
|
112
|
+
| `kx context [<index>]` | List kubeconfig contexts, or switch to an indexed one; alias: kx contexts. |
|
|
113
|
+
| `kx state [<position>] [--all/-a]` | Show current state, jump to a history position, or list all entries with --all. |
|
|
114
|
+
| `kx drop <position>` | Remove a history entry by position (shown in kx state --all). |
|
|
115
|
+
| `kx back` | Navigate to the previous kx get result. |
|
|
116
|
+
| `kx forward` | Navigate to the next kx get result. |
|
|
117
|
+
| `kx theme [<name>]` | List available color themes or persist a choice by name or index. |
|
|
118
|
+
<!-- commands-table-end -->
|
|
119
|
+
|
|
120
|
+
### Triage a namespace
|
|
121
|
+
|
|
122
|
+
Bare `kx diag` sweeps the current namespace — Deployments, StatefulSets,
|
|
123
|
+
DaemonSets, Jobs, CronJobs, Services, and PersistentVolumeClaims, plus pods
|
|
124
|
+
nothing owns — and prints a ranked table of what's unhealthy. Findings also
|
|
125
|
+
draw on live resource usage (`kx top`): a pod running hot against its memory
|
|
126
|
+
limit is flagged as an OOMKill risk before it dies. The rows are indexed, so
|
|
127
|
+
`kx diag 1` or `kx logs 2` drill straight in.
|
|
128
|
+
|
|
129
|
+
<div align="center">
|
|
130
|
+
<img src="https://raw.githubusercontent.com/jzills/kx/main/demo/diag.gif" alt="kx diag demo" width="800"/>
|
|
131
|
+
</div>
|
|
132
|
+
|
|
133
|
+
`kx diag <index>` diagnoses a single resource: a verdict banner, a `SUMMARY`
|
|
134
|
+
of findings (CrashLoopBackOff, image pull failures, OOMKills, unschedulable
|
|
135
|
+
pods, stalled rollouts, missing Service endpoints, Pending PVCs, failed
|
|
136
|
+
CronJob runs, usage near limits), a per-pod status table, recent log tails
|
|
137
|
+
from broken containers, and warning events — one screen instead of four
|
|
138
|
+
kubectl commands.
|
|
139
|
+
|
|
140
|
+
### Read a Secret in plaintext
|
|
141
|
+
|
|
142
|
+
`kx secret <index> --decode` prints an indexed Secret's keys and values
|
|
143
|
+
decoded, instead of the base64 kubectl returns. Values that aren't text show a
|
|
144
|
+
`<binary, N bytes>` placeholder rather than garbling the table. `--key`/`-k`
|
|
145
|
+
prints a single value raw — no banner, no wrapping — so it drops straight into
|
|
146
|
+
a shell: `export PGPASSWORD=$(kx secret 1 --decode -k password)`, or redirect a
|
|
147
|
+
binary value to a file. Bare `kx secret --decode` decodes every Secret in the
|
|
148
|
+
namespace in one call, `-n` included — it confirms first unless you pass
|
|
149
|
+
`--yes`/`-y`, since that prints every credential in the namespace.
|
|
150
|
+
|
|
151
|
+
<div align="center">
|
|
152
|
+
<img src="https://raw.githubusercontent.com/jzills/kx/main/demo/secret.gif" alt="kx secret --decode demo" width="800"/>
|
|
153
|
+
</div>
|
|
154
|
+
|
|
155
|
+
### Scan images for vulnerabilities
|
|
156
|
+
|
|
157
|
+
`kx scan <index>` scans the unique container images of an indexed workload
|
|
158
|
+
(init containers and CronJob job templates included); bare `kx scan` sweeps
|
|
159
|
+
every workload in the namespace. Results come back as a severity summary,
|
|
160
|
+
or the full per-image CVE report with `--full`. Requires
|
|
161
|
+
[Docker Scout](https://docs.docker.com/scout/).
|
|
162
|
+
|
|
163
|
+
<div align="center">
|
|
164
|
+
<img src="https://raw.githubusercontent.com/jzills/kx/main/demo/scan.gif" alt="kx scan demo" width="800"/>
|
|
165
|
+
</div>
|
|
166
|
+
|
|
167
|
+
## State
|
|
168
|
+
|
|
169
|
+
`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.
|
|
170
|
+
|
|
171
|
+
## Configuration
|
|
172
|
+
|
|
173
|
+
`kx` reads `~/.kx/config.toml`; environment variables override file settings.
|
|
174
|
+
|
|
175
|
+
| Key | Env var | Default | Description |
|
|
176
|
+
| --- | --- | --- | --- |
|
|
177
|
+
| `max_history` | `KX_MAX_HISTORY` | `10` | Number of `kx get` results kept in history. |
|
|
178
|
+
| `shells` | `KX_SHELLS` (comma-separated) | `["bash", "sh"]` | Shell candidates for `kx exec`. |
|
|
179
|
+
| `no_color` | `KX_NO_COLOR` | `false` | Disable styled output (same as `--no-color`). |
|
|
180
|
+
| `theme` | `KX_THEME` | `"github-dark"` | Color theme for all output. |
|
|
181
|
+
|
|
182
|
+
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.
|
|
183
|
+
|
|
184
|
+
## Themes
|
|
185
|
+
|
|
186
|
+
`kx theme` lists the available themes with a preview of each; `kx theme <name|index>` persists a choice to `~/.kx/config.toml`.
|
|
187
|
+
|
|
188
|
+
<div align="center">
|
|
189
|
+
<img src="https://raw.githubusercontent.com/jzills/kx/main/demo/theme.gif" alt="kx theme demo" width="800"/>
|
|
190
|
+
</div>
|
|
191
|
+
|
|
192
|
+
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).
|
|
193
|
+
|
|
194
|
+
## Development
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
python -m venv .venv
|
|
198
|
+
source .venv/bin/activate
|
|
199
|
+
pip install -e ".[dev]"
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Run the CLI directly:
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
python -m kx.main --help
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
The demo GIFs are rendered from [VHS](https://github.com/charmbracelet/vhs)
|
|
209
|
+
tapes — see [`demo/README.md`](demo/README.md) for seeding the demo namespace
|
|
210
|
+
and re-recording.
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
kx_cli-0.1.0.data/scripts/kx.exe,sha256=tV_hP0QW9vjFjEX3wdwHNU85E_EBui6l2iUP2c1tGOc,42813440
|
|
2
|
+
kx_cli-0.1.0.dist-info/METADATA,sha256=6ZJrrEbMKvBkrCTE6XUQ5Z6v3sQ3hcP3YWhsoYOfS4c,11134
|
|
3
|
+
kx_cli-0.1.0.dist-info/WHEEL,sha256=PLEJfJBitAfIBdkgDA3JIHtocxQPmTHEvmJ-ne_4KNc,96
|
|
4
|
+
kx_cli-0.1.0.dist-info/RECORD,,
|