kube-query 0.1.0__tar.gz

kube_query-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kube-query contributors
+
+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.

kube_query-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: kube-query
+Version: 0.1.0
+Summary: Read-only Kubernetes query CLI - compact YAML/JSON/rich/markdown output, built for humans and AI agents
+License-Expression: MIT
+Keywords: kubernetes,kubectl,cli,query,read-only,ai-agents,troubleshooting,helm,eks,external-secrets
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Clustering
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: kubernetes>=28.1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# kube-query
+
+**`kq` — read-only Kubernetes queries for humans and AI agents.**
+
+kubectl is a loaded gun in an agent's hands. kube-query is the safe scope:
+it **captures cluster state and diagnoses problems**, and *cannot* create,
+update or delete anything — the HTTP layer implements `GET` and nothing else.
+Compact YAML by default, with rich tables, markdown, JSON and ownership
+trees on request. Built-ins, shortnames, CRDs, Helm releases and External
+Secrets Operator — one small, fast binary-ish CLI.
+
+```
+kq p l -A                    # all pods, all namespaces
+kq p desc web-5d9c6 -n prod  # status + reasons + restarts + events, one doc
+kq logs web-5d9c6 -n prod -c app --previous
+kq tree deploy/web -n prod   # Deployment -> ReplicaSet -> Pods, health per node
+kq overview                  # whole-cluster snapshot, problems first
+```
+
+> kq is the **diagnosis** half of the loop. The **fix** half belongs to other
+> tools (kubectl apply, gitops, helm) — by design.
+
+## Why
+
+| Problem with `kubectl` for agents | kube-query |
+|---|---|
+| can `delete`/`scale`/`apply` — one hallucinated flag away from an incident | GET-only; no mutating code path exists |
+| `-o yaml` dumps managedFields/uid/annotations noise into context | compact by default, `-v`/`-vv` for more |
+| output shaped for terminals, not reasoning | yaml/json data, md reports, tree views |
+| 100+ verbs to misuse | ~15 read verbs with aliases (`kq p l`, `kq d l`, `kq c l`) |
+| helm/ESO/CRD troubleshooting needs extra tools | helm releases, ESO status and CRDs built in |
+
+## Install
+
+Requires Python 3.13+.
+
+```bash
+pipx install kube-query          # or: uv tool install kube-query
+kq ctx ls                        # verify — reads your existing kubeconfig
+```
+
+From source:
+
+```bash
+git clone <repo> && cd kube-query
+make setup                       # .venv (py3.13) + dev deps
+.venv/bin/kq overview
+```
+
+No cluster to try it on? `make demo` boots a fake API server with broken
+pods, a stuck deployment, helm releases and ESO resources to poke at.
+
+## Commands
+
+| Command (aliases) | Purpose |
+|---|---|
+| `kq overview` (`ov`, `o`, `health`) | cluster snapshot: problem pods, nodes, deployments, PVCs, warnings |
+| `kq pod` (`pods`, `p`, `po`) | `l [REGEX] [-A\|-n\|-l\|--field-selector]` · `NAME` · `desc NAME` · `logs NAME` |
+| `kq deploy` (`deployments`, `dep`, `d`) | same shape for deployments |
+| `kq ns` (`n`) · `kq node` (`no`) · `kq svc` · `kq cm` | namespaces, nodes, services, configmaps |
+| `kq secret` (`sec`) | values hidden; `kq sec NAME --reveal` decodes (explicit opt-in) |
+| `kq ev` (`events`, `e`) | events, newest first: `--type Warning --since 2h --for pod/NAME` |
+| `kq get RESOURCE[/NAME]` (`g`) | any resource incl. CRDs; `kq api` lists all types |
+| `kq describe` (`desc`) | diagnosis bundle: summary + object + children + events |
+| `kq tree RESOURCE/NAME` (`t`) | ownership tree (`deploy/web`, `cronjob/x`, `node/y`) |
+| `kq helm` (`h`) | releases read-only from Helm's release Secrets; `show NAME` adds values |
+| `kq eso` | ExternalSecret sync status (`--stores` for SecretStores) |
+| `kq ctx` (`c`) | kubeconfig contexts (`kq c l`), no API calls |
+| `kq ver` | client + server version (which cluster am I on?) |
+
+Shared flags: `-n NS` · `-A` · `-l SELECTOR` · `--field-selector` · `-f/--filter REGEX`
+· `-o yaml|json|rich|md|tree` (default yaml, `KQ_OUTPUT` env) · `-v`/`-vv`.
+
+## Output
+
+```bash
+kq overview -o rich      # aligned, colored tables (humans)
+kq p l -A -o md          # markdown tables (tickets, chat, agent reports)
+kq p web-5d9c6 -o json   # machine-readable
+kq d l -o tree           # ownership view
+```
+
+Stdout is always the payload (parseable); commentary goes to stderr as
+`#`-prefixed notes. Exit codes: `0` ok, `1` error (one actionable sentence),
+`2` usage.
+
+## For AI agents
+
+Give your agent (Claude Code, opencode, codex, …) the one-file skill:
+[`SKILL.md`](SKILL.md) — command map, the 5-move triage loop, output
+contract, failure-signature table, and rules of engagement. Suggested
+system-prompt line:
+
+> Use `kq` (read-only) to inspect the Kubernetes cluster: start with
+> `kq overview`, then `kq p desc <pod>`, `kq logs`, `kq tree`, `kq ev`.
+> Never attempt cluster changes with kq; propose them for kubectl instead.
+
+## Documentation
+
+| Doc | Contents |
+|---|---|
+| [docs/usage.md](docs/usage.md) | full manual: every command, flag, format, exit code |
+| [docs/tutorial.md](docs/tutorial.md) | hands-on: debugging a broken deployment end-to-end |
+| [docs/architecture.md](docs/architecture.md) | module map + data flow diagrams |
+| [docs/extending.md](docs/extending.md) | add commands, columns, formats (with examples) |
+| [docs/roadmap.md](docs/roadmap.md) | what's next + explicit non-goals |
+| [CHANGELOG.md](CHANGELOG.md) | releases |
+
+## Development
+
+```bash
+make setup          # venv + deps
+make check          # the full gate: ruff lint + format check + pytest + build
+make demo           # fake-cluster playground
+make tag            # run the gate, then create v<version> tag
+git push origin vX.Y.Z   # CI publishes to PyPI (trusted publishing)
+```
+
+Pipeline: `make check` mirrors CI exactly; pushing a `v*` tag runs the same
+gate, builds sdist+wheel, verifies tag/version match, and publishes via
+GitHub Actions to PyPI — no stored secrets (OIDC trusted publishing).
+
+Tests are network-free: unit suites plus smoke tests that drive the real CLI
+against an in-process fake Kubernetes API server.
+
+## Safety model
+
+1. `kube_query/http.py` exposes `raw_get` only — there is no verb parameter anywhere.
+2. `kube_query/access.py` builds list/get/log paths only.
+3. Secret values are redacted unless `--reveal` is passed explicitly.
+4. Your RBAC still applies — kq reads exactly what your credentials allow.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

kube_query-0.1.0/README.md

@@ -0,0 +1,135 @@
+# kube-query
+
+**`kq` — read-only Kubernetes queries for humans and AI agents.**
+
+kubectl is a loaded gun in an agent's hands. kube-query is the safe scope:
+it **captures cluster state and diagnoses problems**, and *cannot* create,
+update or delete anything — the HTTP layer implements `GET` and nothing else.
+Compact YAML by default, with rich tables, markdown, JSON and ownership
+trees on request. Built-ins, shortnames, CRDs, Helm releases and External
+Secrets Operator — one small, fast binary-ish CLI.
+
+```
+kq p l -A                    # all pods, all namespaces
+kq p desc web-5d9c6 -n prod  # status + reasons + restarts + events, one doc
+kq logs web-5d9c6 -n prod -c app --previous
+kq tree deploy/web -n prod   # Deployment -> ReplicaSet -> Pods, health per node
+kq overview                  # whole-cluster snapshot, problems first
+```
+
+> kq is the **diagnosis** half of the loop. The **fix** half belongs to other
+> tools (kubectl apply, gitops, helm) — by design.
+
+## Why
+
+| Problem with `kubectl` for agents | kube-query |
+|---|---|
+| can `delete`/`scale`/`apply` — one hallucinated flag away from an incident | GET-only; no mutating code path exists |
+| `-o yaml` dumps managedFields/uid/annotations noise into context | compact by default, `-v`/`-vv` for more |
+| output shaped for terminals, not reasoning | yaml/json data, md reports, tree views |
+| 100+ verbs to misuse | ~15 read verbs with aliases (`kq p l`, `kq d l`, `kq c l`) |
+| helm/ESO/CRD troubleshooting needs extra tools | helm releases, ESO status and CRDs built in |
+
+## Install
+
+Requires Python 3.13+.
+
+```bash
+pipx install kube-query          # or: uv tool install kube-query
+kq ctx ls                        # verify — reads your existing kubeconfig
+```
+
+From source:
+
+```bash
+git clone <repo> && cd kube-query
+make setup                       # .venv (py3.13) + dev deps
+.venv/bin/kq overview
+```
+
+No cluster to try it on? `make demo` boots a fake API server with broken
+pods, a stuck deployment, helm releases and ESO resources to poke at.
+
+## Commands
+
+| Command (aliases) | Purpose |
+|---|---|
+| `kq overview` (`ov`, `o`, `health`) | cluster snapshot: problem pods, nodes, deployments, PVCs, warnings |
+| `kq pod` (`pods`, `p`, `po`) | `l [REGEX] [-A\|-n\|-l\|--field-selector]` · `NAME` · `desc NAME` · `logs NAME` |
+| `kq deploy` (`deployments`, `dep`, `d`) | same shape for deployments |
+| `kq ns` (`n`) · `kq node` (`no`) · `kq svc` · `kq cm` | namespaces, nodes, services, configmaps |
+| `kq secret` (`sec`) | values hidden; `kq sec NAME --reveal` decodes (explicit opt-in) |
+| `kq ev` (`events`, `e`) | events, newest first: `--type Warning --since 2h --for pod/NAME` |
+| `kq get RESOURCE[/NAME]` (`g`) | any resource incl. CRDs; `kq api` lists all types |
+| `kq describe` (`desc`) | diagnosis bundle: summary + object + children + events |
+| `kq tree RESOURCE/NAME` (`t`) | ownership tree (`deploy/web`, `cronjob/x`, `node/y`) |
+| `kq helm` (`h`) | releases read-only from Helm's release Secrets; `show NAME` adds values |
+| `kq eso` | ExternalSecret sync status (`--stores` for SecretStores) |
+| `kq ctx` (`c`) | kubeconfig contexts (`kq c l`), no API calls |
+| `kq ver` | client + server version (which cluster am I on?) |
+
+Shared flags: `-n NS` · `-A` · `-l SELECTOR` · `--field-selector` · `-f/--filter REGEX`
+· `-o yaml|json|rich|md|tree` (default yaml, `KQ_OUTPUT` env) · `-v`/`-vv`.
+
+## Output
+
+```bash
+kq overview -o rich      # aligned, colored tables (humans)
+kq p l -A -o md          # markdown tables (tickets, chat, agent reports)
+kq p web-5d9c6 -o json   # machine-readable
+kq d l -o tree           # ownership view
+```
+
+Stdout is always the payload (parseable); commentary goes to stderr as
+`#`-prefixed notes. Exit codes: `0` ok, `1` error (one actionable sentence),
+`2` usage.
+
+## For AI agents
+
+Give your agent (Claude Code, opencode, codex, …) the one-file skill:
+[`SKILL.md`](SKILL.md) — command map, the 5-move triage loop, output
+contract, failure-signature table, and rules of engagement. Suggested
+system-prompt line:
+
+> Use `kq` (read-only) to inspect the Kubernetes cluster: start with
+> `kq overview`, then `kq p desc <pod>`, `kq logs`, `kq tree`, `kq ev`.
+> Never attempt cluster changes with kq; propose them for kubectl instead.
+
+## Documentation
+
+| Doc | Contents |
+|---|---|
+| [docs/usage.md](docs/usage.md) | full manual: every command, flag, format, exit code |
+| [docs/tutorial.md](docs/tutorial.md) | hands-on: debugging a broken deployment end-to-end |
+| [docs/architecture.md](docs/architecture.md) | module map + data flow diagrams |
+| [docs/extending.md](docs/extending.md) | add commands, columns, formats (with examples) |
+| [docs/roadmap.md](docs/roadmap.md) | what's next + explicit non-goals |
+| [CHANGELOG.md](CHANGELOG.md) | releases |
+
+## Development
+
+```bash
+make setup          # venv + deps
+make check          # the full gate: ruff lint + format check + pytest + build
+make demo           # fake-cluster playground
+make tag            # run the gate, then create v<version> tag
+git push origin vX.Y.Z   # CI publishes to PyPI (trusted publishing)
+```
+
+Pipeline: `make check` mirrors CI exactly; pushing a `v*` tag runs the same
+gate, builds sdist+wheel, verifies tag/version match, and publishes via
+GitHub Actions to PyPI — no stored secrets (OIDC trusted publishing).
+
+Tests are network-free: unit suites plus smoke tests that drive the real CLI
+against an in-process fake Kubernetes API server.
+
+## Safety model
+
+1. `kube_query/http.py` exposes `raw_get` only — there is no verb parameter anywhere.
+2. `kube_query/access.py` builds list/get/log paths only.
+3. Secret values are redacted unless `--reveal` is passed explicitly.
+4. Your RBAC still applies — kq reads exactly what your credentials allow.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

kube_query-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kube-query"
+version = "0.1.0"
+description = "Read-only Kubernetes query CLI - compact YAML/JSON/rich/markdown output, built for humans and AI agents"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.13"
+keywords = ["kubernetes", "kubectl", "cli", "query", "read-only", "ai-agents", "troubleshooting", "helm", "eks", "external-secrets"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: System :: Clustering",
+  "Topic :: System :: Systems Administration",
+]
+dependencies = [
+  "click>=8.1",
+  "kubernetes>=28.1.0",
+  "pyyaml>=6.0",
+  "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+kube-query = "kube_query.cli:main"
+kq = "kube_query.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+kube_query = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+  "E",   # pycodestyle errors
+  "W",   # pycodestyle warnings
+  "F",   # pyflakes
+  "I",   # isort
+  "UP",  # pyupgrade
+  "B",   # flake8-bugbear
+  "C4",  # flake8-comprehensions
+  "SIM", # flake8-simplify
+  "RUF", # ruff-specific
+]
+ignore = [
+  "E501",   # long lines handled by formatter
+  "SIM108", # ternary rewrites hurt readability here
+  "SIM105", # contextlib.suppress rewrites hurt readability
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["E402"]  # conftest-style imports after sys.path tweaks
+
+[tool.ruff.format]
+quote-style = "double"

kube_query-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kube_query-0.1.0/src/kube_query/__init__.py

@@ -0,0 +1,3 @@
+"""kube-query - read-only Kubernetes query CLI for humans and AI agents."""
+
+__version__ = "0.1.0"

kube_query-0.1.0/src/kube_query/access.py

@@ -0,0 +1,85 @@
+"""Object-level access: list/get any resource by its ApiResource, read pod logs."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from .config import Ctx
+from .discovery import ApiResource
+from .errors import KqApiError, KqError
+from .http import get_json, get_text
+
+
+def resource_path(entry: ApiResource, namespace: str | None = None, name: str | None = None) -> str:
+    if entry.group:
+        base = f"/apis/{quote(entry.api_version, safe='/')}"
+    else:
+        base = f"/api/{entry.version}"
+    if entry.namespaced and namespace:
+        base += f"/namespaces/{quote(namespace, safe='')}"
+    base += f"/{entry.plural}"
+    if name:
+        base += f"/{quote(name, safe='')}"
+    return base
+
+
+def list_objects(
+    ctx: Ctx,
+    entry: ApiResource,
+    *,
+    namespace: str | None = None,
+    label_selector: str | None = None,
+    field_selector: str | None = None,
+) -> list[dict]:
+    """List objects. ``namespace=None`` on a namespaced resource lists all namespaces."""
+    if not entry.namespaced and namespace:
+        namespace = None
+    params = {"labelSelector": label_selector, "fieldSelector": field_selector}
+    data = get_json(ctx.api_client, resource_path(entry, namespace), params)
+    items = data.get("items")
+    if not isinstance(items, list):
+        raise KqError(f"unexpected response while listing {entry.plural}")
+    return items
+
+
+def get_object(ctx: Ctx, entry: ApiResource, name: str, *, namespace: str | None = None) -> dict:
+    if entry.namespaced and not namespace:
+        raise KqError(f"internal: namespace required to fetch a namespaced {entry.kind}")
+    try:
+        return get_json(ctx.api_client, resource_path(entry, namespace, name))
+    except KqApiError as e:
+        if e.status == 404:
+            where = f" in namespace '{namespace}'" if entry.namespaced else ""
+            scope = f" -n {namespace}" if entry.namespaced else ""
+            alt = " (or -A for all namespaces)" if entry.namespaced else ""
+            raise KqError(
+                f"{entry.kind} '{name}' not found{where}.\n"
+                f"  Hint: list candidates with 'kq get {entry.plural}{scope}'{alt}."
+            ) from None
+        raise
+
+
+def pod_logs(
+    ctx: Ctx,
+    namespace: str,
+    pod: str,
+    *,
+    container: str | None = None,
+    tail: int | None = None,
+    previous: bool = False,
+    since_seconds: int | None = None,
+    timestamps: bool = False,
+) -> str:
+    path = f"/api/v1/namespaces/{quote(namespace, safe='')}/pods/{quote(pod, safe='')}/log"
+    params = {
+        "container": container,
+        "tailLines": tail,
+        "previous": "true" if previous else None,
+        "sinceSeconds": since_seconds,
+        "timestamps": "true" if timestamps else None,
+    }
+    return get_text(ctx.api_client, path, params)
+
+
+def server_version(ctx: Ctx) -> dict:
+    return get_json(ctx.api_client, "/version")

kube_query-0.1.0/src/kube_query/cleanup.py

@@ -0,0 +1,115 @@
+"""Output compaction: strip agent-irrelevant noise from Kubernetes objects.
+
+Verbosity levels::
+
+    0  (default)  drop managedFields, uid, resourceVersion, generation,
+                  selfLink, noisy annotations, and all empty values
+    1  (-v)       drop managedFields and noisy annotations only
+    2  (-vv)      raw object, nothing is stripped
+"""
+
+from __future__ import annotations
+
+import base64
+
+NOISY_META = ("managedFields", "selfLink", "resourceVersion", "uid", "generation")
+NOISY_ANNOTATIONS = (
+    "kubectl.kubernetes.io/last-applied-configuration",
+    "deployment.kubernetes.io/revision",
+    "deprecated.daemonset.template.generation",
+)
+_EMPTY = ("", {}, [], None)
+
+
+def compact(obj: dict | list, verbose: int = 0) -> dict | list:
+    if verbose >= 2:
+        return obj
+    obj = _strip_noisy(obj)
+    if verbose == 0:
+        obj = _drop_empty(obj)
+    return obj
+
+
+def _strip_noisy(node):
+    if isinstance(node, dict):
+        out = {}
+        for k, v in node.items():
+            if k == "metadata" and isinstance(v, dict):
+                v = {mk: mv for mk, mv in v.items() if mk != "managedFields"}
+                ann = v.get("annotations")
+                if isinstance(ann, dict):
+                    ann = {a: b for a, b in ann.items() if a not in NOISY_ANNOTATIONS}
+                    if ann:
+                        v["annotations"] = ann
+                    else:
+                        v.pop("annotations", None)
+                out[k] = _strip_noisy(v)
+                continue
+            out[k] = _strip_noisy(v)
+        return out
+    if isinstance(node, list):
+        return [_strip_noisy(x) for x in node]
+    return node
+
+
+def _drop_empty(node):
+    if isinstance(node, dict):
+        out = {}
+        for k, v in node.items():
+            if k == "metadata" and isinstance(v, dict):
+                v = {mk: mv for mk, mv in v.items() if mk not in NOISY_META}
+            v = _drop_empty(v)
+            if v in _EMPTY:
+                continue
+            out[k] = v
+        return out
+    if isinstance(node, list):
+        return [_drop_empty(x) for x in node]
+    return node
+
+
+# -- display helpers for ConfigMaps / Secrets ------------------------------
+
+
+def cap_map_values(obj: dict, limit: int = 2000) -> dict:
+    """Cap long string values in data maps (ConfigMap display) in place."""
+    for key in ("data", "stringData", "binaryData"):
+        m = obj.get(key)
+        if not isinstance(m, dict):
+            continue
+        for k, v in list(m.items()):
+            if isinstance(v, str) and len(v) > limit:
+                m[k] = v[:limit] + f" ...[truncated {len(v) - limit} of {len(v)} chars; -v to see full]"
+    return obj
+
+
+def redact_map_values(obj: dict) -> dict:
+    """Hide secret values in place; keys and sizes stay visible."""
+    for key in ("data", "stringData", "binaryData"):
+        m = obj.get(key)
+        if not isinstance(m, dict):
+            continue
+        obj[key] = {k: (f"<{len(v)} chars hidden -- use --reveal>" if isinstance(v, str) else v) for k, v in m.items()}
+    return obj
+
+
+def reveal_map_values(obj: dict) -> dict:
+    """Base64-decode secret data values in place (binary values stay encoded)."""
+    m = obj.get("data")
+    if isinstance(m, dict):
+        out = {}
+        for k, v in m.items():
+            if not isinstance(v, str):
+                out[k] = v
+                continue
+            try:
+                raw = base64.b64decode(v)
+            except Exception:
+                out[k] = v
+                continue
+            try:
+                out[k] = raw.decode("utf-8")
+            except UnicodeDecodeError:
+                out[k] = f"<{len(raw)} bytes binary; base64: {v[:100]}>"
+        obj["data"] = out
+    return obj

kube_query-0.1.0/src/kube_query/cli.py

@@ -0,0 +1,81 @@
+"""kq — read-only Kubernetes queries for humans and AI agents."""
+
+from __future__ import annotations
+
+import click
+
+from . import __version__
+from .cli_kit import KqGroup
+from .commands import register
+from .config import Settings
+from .output import FORMATS
+
+EPILOG = """\
+\b
+USAGE PATTERNS
+  kq overview                        cluster snapshot: problems first
+  kq p l [-A|-n NS] [REGEX]          list pods          (d=deploy, n=ns, no=node,
+  kq p NAME / p desc NAME            inspect            sec=secret, cm, svc, ev)
+  kq logs NAME [-c C] [--tail N]     pod logs           kq tree deploy/NAME
+  kq get RESOURCE[/NAME]             any resource incl. CRDs; kq api lists all
+  kq helm ls -A / kq eso -A          helm releases / ExternalSecret status
+
+\b
+OPTIONS
+  -o yaml|json|rich|md|tree          output (default: compact yaml)
+  -n NS | -A | -l SELECTOR | -f RX   scope: namespace / all / labels / name regex
+  -v (system metadata) -vv (raw)     verbosity
+  --ctx NAME / --kubeconfig PATH     cluster selection
+
+\b
+ROLE
+  kq CAPTURES cluster state for diagnosis; fixing belongs to other tools
+  (kubectl apply, gitops, helm). kq only sends GET requests - it can
+  never create, update or delete anything.
+"""
+
+
+@click.group(
+    cls=KqGroup,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.version_option(__version__, "--version", prog_name="kube-query")
+@click.option("--ctx", "--context", "context", default=None, help="Kubeconfig context to use.")
+@click.option("--kubeconfig", default=None, type=click.Path(exists=True), help="Path to a kubeconfig file.")
+@click.option("-n", "--ns", "--namespace", "namespace", default=None, help="Default namespace for this invocation.")
+@click.option(
+    "-A", "--all-namespaces", "all_namespaces", is_flag=True, default=False, help="All namespaces (where applicable)."
+)
+@click.option(
+    "-o",
+    "--output",
+    "output_fmt",
+    type=click.Choice(FORMATS),
+    default=None,
+    help="Output format: yaml, json, rich, md, tree. [env: KQ_OUTPUT]",
+)
+@click.option("-v", "--verbose", count=True, help="Verbosity: -v keep system metadata, -vv raw object.")
+@click.pass_context
+def main(ctx, context, kubeconfig, namespace, all_namespaces, output_fmt, verbose):
+    """kq - read-only Kubernetes queries for AI agents and humans.
+
+    Compact yaml by default; rich tables, markdown, json and ownership
+    trees on request. Built-ins, shortnames, CRDs, Helm releases and
+    External Secrets Operator. Start with: kq overview
+    """
+    ctx.obj = Settings(
+        context=context,
+        kubeconfig=kubeconfig,
+        namespace=namespace,
+        output=output_fmt,
+        verbose=verbose,
+        all_namespaces=all_namespaces,
+    )
+
+
+main.epilog = EPILOG
+register(main)
+
+
+if __name__ == "__main__":
+    main()