KubeAstra CLI

AI-powered Kubernetes troubleshooting from your terminal. A thin HTTP + SSE client for the KubeAstra backend.

$ kubeastra investigate --pod api-gateway --ns production

$ kubeastra investigate
  thinking · The user wants a scoped investigation of api-gateway in production …
 kubectl  get_pods returned 1 result (48ms)
 kubectl  describe_pod api-gateway (162ms)
 logs     get_pod_logs — last 200 lines (89ms)
 events   correlated 3 recent events (54ms)
 analyze  investigate_pod complete (912ms)

─ answer ─
Root cause: OOMKilled. Container RSS 142Mi exceeded limit 128Mi.
Trigger: Memory leak introduced in v2.3.1 (deployed 47 min ago).

╭─ KubeAstra ─────────────────────────────────────────────────────────╮
│                                                                     │
│  Root cause                                                         │
│                                                                     │
│  The api-gateway container was OOMKilled 3 times in the last 30     │
│  minutes. Its resident memory (142Mi) exceeded the configured limit │
│  (128Mi) shortly after each restart. The pattern started at         │
│  14:23 UTC, coinciding with the v2.3.1 rollout at 14:22 UTC.        │
│                                                                     │
│  Recommended: Rollback to v2.3.0 · blast radius: 2 services         │
│                                                                     │
╰─ tool: investigate_pod · cost: $0.0021 · tokens: 640 ─────────────────╯

Install

pip / pipx (recommended for standalone use):

pipx install kubeastra

From the monorepo (for contributors):

git clone https://github.com/astraverse-io/KubeAstra.git
cd KubeAstra/cli
pip install -e .

Python 3.11 or newer is required.

Prerequisites

The CLI talks to a KubeAstra backend over HTTP + Server-Sent Events. Start one before running commands:

# Local backend via docker-compose (from the monorepo root):
cd ui && docker compose up -d --build
# Backend listens on http://localhost:8000 by default.

Or point the CLI at an existing Helm-deployed backend:

kubeastra config set backend-url https://kubeastra.mycompany.internal

Commands

kubeastra open

Run the whole product locally as an app — no Docker, no cluster install, no backend to start first. This is the exception to the prerequisite above: it is the backend.

kubeastra open                # starts the app and opens your browser
kubeastra open --no-browser   # start it, print the URL, open it yourself

It binds a loopback-only port, serves the built UI from that same origin, and uses the kubeconfig already on this machine. Nothing is installed into any cluster, and nothing listens on an external interface.

Requires the UI to have been built once from a source checkout:

npm run build:desktop --prefix ui/frontend

kubeastra ask "..."

Natural-language investigation. Streams the ReAct loop step-by-step.

kubeastra ask "why is checkout-service crashlooping in production?"
kubeastra ask "what pods are in the payments namespace?"

kubeastra investigate

Scoped investigation shortcut — same underlying flow as ask, with a canned question.

kubeastra investigate --pod api-gateway --ns production
kubeastra investigate --deployment redis --ns default
kubeastra investigate --node k8s-worker-01

kubeastra connect

Pick a kubeconfig context. Without arguments, lists what's available.

kubeastra connect                            # list contexts
kubeastra connect --context prod-us-east-1   # connect to a specific context
kubeastra connect --context dev --kubeconfig ~/.kube/other-config

kubeastra config set / get

Persist backend URL, API token (if the backend enforces auth), and session id.

kubeastra config set backend-url https://kubeastra.example.com
kubeastra config set api-token ka_prod_abcdef1234567890
kubeastra config get                         # print all values (token masked)
kubeastra config get backend-url             # print a specific value
kubeastra config path                        # print the config file path

Config lives at ~/.config/kubeastra/config.toml on Linux/macOS ($XDG_CONFIG_HOME/kubeastra/config.toml when set) and %APPDATA%\kubeastra\config.toml on Windows.

kubeastra doctor

Health-check the CLI + backend + kubeconfig detection.

kubeastra doctor

kubeastra --version

Print the CLI version.

Exit codes

Design notes

• The CLI is a client, not an engine. The ReAct loop, tool dispatch, and RAG live in the backend. This is by design — one implementation of the agent, three surfaces (web UI, MCP server, this CLI).
• No offline mode. Air-gapped deployments should run the backend Helm chart on-cluster and point the CLI at the internal service.
• No secrets in the config file beyond what you put there. The api_token field is intentionally the only persisted credential.
• No telemetry. The CLI does not phone home. Only the backend URL you configure is contacted.

Related

• KubeAstra README — the full project
• Web UI — the same investigations, in a browser
• MCP server — the same tools, in your IDE (Cursor / Claude Desktop)
• Marketing site

License

Apache 2.0 — see LICENSE.