Metadata-Version: 2.4
Name: kubeastra
Version: 0.2.3
Summary: CLI for KubeAstra — AI-powered Kubernetes troubleshooting
Author: KubeAstra contributors
License: Apache-2.0
Project-URL: Homepage, https://kubeastra.io
Project-URL: Repository, https://github.com/astraverse-io/KubeAstra
Project-URL: Issues, https://github.com/astraverse-io/KubeAstra/issues
Keywords: kubernetes,k8s,ai,troubleshooting,kubectl,sre,devops
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: httpx-sse>=0.4.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.30.0; extra == "dev"
Requires-Dist: syrupy>=4.6.0; extra == "dev"

# KubeAstra CLI

[![PyPI version](https://img.shields.io/pypi/v/kubeastra.svg)](https://pypi.org/project/kubeastra/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../LICENSE)

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):**
```bash
pipx install kubeastra
```

**From the monorepo (for contributors):**
```bash
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:

```bash
# 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:

```bash
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.

```bash
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:

```bash
npm run build:desktop --prefix ui/frontend
```

### `kubeastra ask "..."`
Natural-language investigation. Streams the ReAct loop step-by-step.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
kubeastra doctor
```

### `kubeastra --version`
Print the CLI version.

## Exit codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | Generic CLI error (bad flags, unexpected exception) |
| `2` | Authentication failure — set an API token |
| `3` | Connection failure — backend unreachable |
| `4` | Backend returned a non-2xx status |
| `5` | Backend answered but the investigation itself errored |

## 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](../README.md) — the full project
- [Web UI](../ui/README.md) — the same investigations, in a browser
- [MCP server](../mcp/README.md) — the same tools, in your IDE (Cursor / Claude Desktop)
- [Marketing site](https://kubeastra.io)

## License

Apache 2.0 — see [LICENSE](../LICENSE).
