k8s-cli

oasis-k8s — an AXI-compliant CLI for read-only Kubernetes access across the Oasis clusters. List namespaces, nodes, pods, deployments, services, and events, read pod logs, and describe objects — with token-efficient TOON output built for autonomous agents.

Extracted from the oasis-core Claude Code plugin so it can be installed, versioned, and released on its own.

Quick Start

Install the k8s-cli skill in the Agent Skills format with npx skills:

npx skills add oasissys/k8s-cli --skill k8s-cli -g

That is the entire setup — the skill teaches your agent the CLI, and it runs without a global install as npx -y @oasissys/k8s-cli (Node 20+ required). Installing the skill itself needs GitHub access to this private repo.

-g installs the skill for all projects (~/.claude/skills/); drop it to install for the current project only.

Other ways to install

Zero setup

Any capable agent can run the CLI directly with nothing installed. Just tell your agent:

Execute `npx -y @oasissys/k8s-cli` to get Oasis Kubernetes tools.

Global install + session hook

Want the CLI on PATH and the saved clusters fed into every agent session?

npm install -g @oasissys/k8s-cli   # installs `oasis-k8s` (and the `k8s-cli` alias)
oasis-k8s setup

setup registers a SessionStart hook for Claude Code, Codex, and OpenCode that surfaces the saved clusters at session start — restart your agent session after running it. If you use the oasis-core Claude Code plugin, it already ships this hook; skip setup or remove one of the two.

From a clone (development)

pnpm install && pnpm run build && pnpm link --global

Register clusters

Clusters live in ~/.oasis.json (shared with the other oasis CLIs and the Oasis dashboard) and are verified against the apiserver's /version before being saved. The CLI talks straight to each kube-apiserver with a ServiceAccount bearer token — no kubeconfig, no certs.

oasis-k8s add jeddah --url https://<host>:6443 --token <token>
oasis-k8s clusters              # list saved clusters and the active one
oasis-k8s use jordan            # switch the active cluster
oasis-k8s rm jeddah             # remove a saved cluster

Use

oasis-k8s                                        # live view: saved clusters + active
oasis-k8s pods --namespace default               # pods in one namespace
oasis-k8s nodes                                  # nodes (status + kubelet version)
oasis-k8s logs my-pod --namespace default        # tail a pod's logs (200 lines)
oasis-k8s describe pod my-pod --namespace default # dump one object as JSON
oasis-k8s deployments --cluster jordan           # target a cluster without switching

Every command supports --help. Output is TOON on stdout, diagnostics on stderr, exit codes 0/1/2 (success/error/usage). Every read command is a GET — the CLI never mutates cluster state.

Development

pnpm run dev -- pods --namespace default   # run from source
pnpm test                                   # vitest
pnpm run lint                               # eslint
pnpm run build:skill                        # regenerate SKILL.md

Releases are cut by release-please from conventional commits on main. Do not hand-edit CHANGELOG.md, .release-please-manifest.json, or skills/k8s-cli/SKILL.md — they are generated.