Operate and troubleshoot Kubernetes from the runtimez control plane: what is running, what changed, what is risky, whether a cluster is upgrade-safe, why a workload is slow.
No kubeconfig, no cluster VPN, no browser. rtz reads everything through the runtimez
API, so it works from a laptop on a phone tether at 3am.
brew install runtimez-com/tap/rtzcurl -fsSL https://raw.githubusercontent.com/runtimez-com/runtimez-cli/main/install.sh | shWindows: scoop bucket add runtimez https://github.com/runtimez-com/scoop-bucket && scoop install rtz
Binaries cover macOS, Linux and Windows on amd64 and arm64; .deb, .rpm and .apk
packages are attached to each release. Building from source: make build.
See RELEASING.md for how releases are cut and how to verify a download.
rtz login # browser sign-in
rtz login --token rk_... # or an API key with the api:read scope, for CI
rtz cluster ls
rtz use prod
rtz doctorRun rtz with no arguments for the full-screen UI.
| Key | Action |
|---|---|
: |
browse every screen: the menu lists them grouped (resources, reliability, observability, capacity and lifecycle, add-ons) and narrows as you type — ↑↓ select, tab complete, enter open. A typo gets a "did you mean" |
: |
capacity and lifecycle — :capacity, :pending, :storage, :maintain, :upgrade |
: |
add-on workspaces — :karpenter, :ca, :traefik, :istio, :argocd, :cni, :ebs |
: |
resources and the rest — :pods, :deploy, :sts, :ds, :svc, :ing, :nodes, :all, :risk, :signals, :changes, :logs, :traces, :ns <name>, :q |
1–5 |
switch group — Resources, Reliability, Observability, Capacity, Add-ons — back to the screen you last used there |
tab / shift+tab |
next / previous screen in the group; the two tab lines at the top show both |
/ |
filter the visible rows as you type |
enter / d |
describe the selected workload; on capacity, Maintain, upgrade and add-on screens, open the row's findings with their verify commands |
p |
pause or resume auto-refresh |
ctrl+r |
refresh now |
? |
keys and commands |
q, ctrl+c |
quit |
Auto-refresh runs every 10s (--refresh) and holds while a pane or prompt is open, so the
rows never move under the cursor. --view picks the opening screen.
Every screen has an exact flag equivalent — :deploy is rtz get deploy, d is
rtz describe — because both render from the same column definitions in internal/view.
On a terminal that cannot host the UI (a pipe, a CI log, TERM=dumb) rtz prints help
instead. On Windows use Windows Terminal or PowerShell 7; the legacy console lacks the
virtual-terminal support the UI needs.
rtz ask "why is checkout returning 5xx"
rtz ask "and the memory limits?" --session s-1a2b
rtz ask prompts # curated starter questions
rtz ask sessions # saved conversationsThe investigation streams as it runs — each step names the tool it is about to use and what
that tool returned — so a long run shows progress rather than a blank prompt. ctrl-c
cancels it server-side, not just locally, so an abandoned run stops costing tokens.
--quiet prints only the answer. A run that hits the agent's step limit says so: a partial
investigation otherwise reads exactly like a complete one.
rtz logs --since 15m --level ERROR
rtz logs -s checkout -q 'status:5* AND @http.method:POST'
rtz logs --follow # polls; the API has no log stream
rtz trace list --since 2h --errors
rtz trace get <trace-id> # span tree, nested, errors marked
rtz trace analyze <trace-id>
rtz trace logs <trace-id> # logs correlated to that trace
rtz metrics list --entity-type K8S_POD
rtz metrics query k8s.pod.memory.usage --entity-type K8S_POD --group-by k8s.pod.name --agg max
rtz metrics tags --entity-type K8S_POD --key namespace
rtz metrics entities --entity-type K8S_NODE-q takes the Datadog-style filter language — free text, field:value, @attributes,
wildcards, ranges, AND/OR/NOT. The server rejects an unparseable query rather than
silently matching everything.
--entity-type is required on the metrics endpoints: the API answers a missing one with a
500, so the CLI catches it first and names the flag.
A terminal cannot draw a curve, so metrics query summarises each series as last/min/max
plus the point count, and says when the backend rewrote the query as a per-second rate.
Use -o json for the raw points.
rtz upgrade check # is this cluster safe to upgrade?
rtz upgrade check --target 1.31 --fail-on high
rtz upgrade fleet # every cluster, soonest deadline firstupgrade check warns when the verdict rests on stale inventory or a partial scan, and
names any detection tier that was not fully covered — a readiness score built on old data
otherwise reads exactly like one built on fresh data. Extended-support costs are labelled
ILLUSTRATIVE when the backend has not sourced a real figure.
upgrade fleet reports clusters it could not analyse rather than folding them into a pass.
upgrade check also lists the add-ons that must move with Kubernetes, how many patches the
cluster is behind, and an Applications section: per namespace, what the app team must
change before the upgrade and what is only affected by it.
rtz capacity # headroom per axis, node pools, pending pods
rtz capacity --section blocked # every pending pod and why (pools|nodes|blocked|storage|network|batch|special)
rtz capacity trend --days 30 # growth and days until each pool is full
rtz capacity cost # node cost per pool and the levers that change it
rtz capacity namespaces # requests, quota and pending pods per namespace
rtz capacity fleet # every cluster, soonest-full firstUsage gaps (nodes with no samples), truncated rows, uncollected quotas and unpriced nodes
are stated as warnings — an unread figure prints ? or unpriced, never 0.
rtz maintain items --within 90 # support deadlines across the org, soonest first
rtz maintain items --fail-on-days 30 # CI: exit 4 when a deadline is 30 days away or less
rtz maintain packages --ecosystem maven --q log4j
rtz maintain dependents data/StatefulSet/postgres # who connects to it
rtz maintain impact data/StatefulSet/postgres --target 17Platform items (Kubernetes, add-ons, system workloads) are hidden unless --platform —
rtz upgrade check owns those. A list the backend could not finish reading exits 1.
rtz addons nodepools [name] # Karpenter (alias: karpenter)
rtz addons cluster-autoscaler [group] # alias: ca
rtz addons ingress [ns/name] # Traefik routes (alias: traefik)
rtz addons mesh [ns/name] # Istio (alias: istio)
rtz addons gitops [ns/name] # Argo CD (alias: argocd)
rtz addons vpc-cni [node] # Amazon VPC CNI
rtz addons ebs-csi [node] # Amazon EBS CSI
rtz addons istio --fail-on high # CI gate on add-on findingsWithout an argument each lists its objects with the worst finding; with one it prints that object's findings with the command that verifies each. An add-on that is not installed, not synced or has its rules off says so instead of printing an empty table.
-o json / -o yaml on every command above prints the full server document, not the subset
the tables show.
helm template ./chart | rtz risk check -f - --fail-on highStateless and cluster-free — it needs only a token, so it runs anywhere CI does. An empty manifest is refused rather than scored 0: a template step that silently produced nothing would otherwise be the greenest possible build.
Four axes, all answerable without opening the UI.
rtz risk # scored workloads, worst first (0-100, higher is worse)
rtz risk workload payments/checkout # why this one scored what it did
rtz risk security | cve | compliance
rtz rca # what is degraded right now, and why
rtz rca payments/checkout # evidence: restarts, events, log tail, dependencies
rtz rca explain payments/checkout # narrative root cause
rtz signals # slowest operations by p99
rtz signals traces # slowest individual traces
rtz changes --since 24 # what changed, newest first
rtz changes payments/checkout # one workload's historyrtz risk --fail-on highExits 4 when anything reaches the threshold. An unrecognised severity is a usage error,
not a silent pass — a typo must never turn the gate into a no-op that reports success.
These commands distinguish "nothing is wrong" from "we could not see", because a clean score computed from missing evidence is the most dangerous output this tool could produce:
riskwarns when it scored without metrics, CVE data, runtime or network signals.risk security/cvesay when a cluster has never been scanned, rather than reporting zero findings as clean.rcaprints "no trace data for this workload" instead of a fabricated 0% error rate.rca explainstates whether the answer came from a model, a cache replay, or a deterministic gate — the prose alone does not reveal which.
rtz mcp serves the Runtimez MCP server over stdio, so an MCP client can ask Runtimez
instead of guessing: what is running, what changed, ranked risk findings, the upgrade
readiness ledger with the vendor's verbatim rule text, and a pre-merge manifest check. It
is a bridge — every message is forwarded to the hosted endpoint (POST /eac/mcp) with this
CLI's credential, so the tool catalog is exactly the server's and every tool is read-only.
claude mcp add runtimez -- rtz mcp # uses the current context
claude mcp add runtimez -- rtz mcp --context prod --cluster prod-euRemote clients (Claude Code --transport http, Cursor, claude.ai connectors) can skip the
CLI and point at https://<api>/eac/mcp with Authorization: Bearer rk_... (an API key
with the api:read scope). A --cluster (or the context's cluster) is injected as the
default cluster argument when the client did not pass one.
rtz get pods -n payments # po, deploy, sts, ds, svc, ing, no — or "all"
rtz get deploy -o wide # adds KIND and IMAGE
rtz get pods -l app=web # equality selectors
rtz describe payments/checkout # workload + pods + events + services in one screen
rtz search checkout # substring match over workload names
rtz ns / rtz counts # namespaces, resource counts by kind
rtz fleet # org-wide rollup across every clusterget reads what the agent last synced, so it needs no kubeconfig and no cluster network
access. The server caps a listing at 5000 rows with no pagination — when that cap is hit,
rtz says the list is truncated rather than presenting it as the whole cluster.
Two credential kinds, and they are not interchangeable:
| Kind | How | Reach |
|---|---|---|
API key (rk_…) |
rtz login --token or RTZ_TOKEN |
Must carry the api:read scope. Then authorizes exactly as the user who created it does, for every cluster-scoped command. Carries no role, so org and user administration is out of reach by design. |
| Browser sign-in | rtz login |
Full role parity, including administration. The redirect returns to a listener on 127.0.0.1 that the command opens; over SSH, --no-browser prints the URL and the exact ssh -L line to forward the port. |
An ingest key will not work — ingest:* scopes authorize the ingest gateway, not this
API. Create a separate key with api:read.
Credentials go to the OS keychain when one is reachable, and to a 0600 file otherwise —
which is the normal case on a headless Linux box with no D-Bus session.
Contexts work like kubectl's: a named target holding an API URL, an org, and a cluster.
rtz config get-contexts
rtz config use-context prod
rtz config pathPrecedence is flag → environment → context, so a --flag never loses to a config file.
| Flag | Env | Meaning |
|---|---|---|
--context |
RTZ_CONTEXT |
Which stored context to use |
--api |
RTZ_API |
Backend base URL |
--org |
RTZ_ORG |
Organization id |
--cluster |
RTZ_CLUSTER |
Cluster id |
| — | RTZ_TOKEN |
API key, winning over anything stored |
| — | RTZ_CONFIG |
Config file path |
Every command supports -o table|wide|json|yaml. The JSON is the unwrapped payload — never
the API envelope — so jq needs no .data prefix:
rtz cluster ls -o json | jq -r '.[] | select(.status != "CONNECTED") | .name'Scripts and CI depend on these.
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Runtime error |
2 |
Usage error |
3 |
Authentication required |
4 |
Policy or threshold failure (--fail-on) |
make test # go test ./...
make lint # golangci-lint
make snapshot # build every release target locallyinternal/api is the only package that knows HTTP. The flag commands and (later) the TUI are
both consumers of it, which is what keeps the two surfaces from drifting apart.