kube-q

Chat with your Kubernetes cluster from the terminal.

kube-q is an interactive CLI (kq) that connects to an AI-powered backend and lets you query, debug, and manage your cluster in plain English — with streaming responses, persistent session history, full-text search, conversation branching, token cost tracking, human-in-the-loop approval flows, and rich terminal rendering.

Features

• Interactive REPL — persistent conversation history, slash commands, Tab completion
• Streaming responses — tokens render in real-time via Server-Sent Events
• Session persistence & resume — every conversation is saved to a local SQLite database; resume any past session with kq --session-id <id> from the shell or pick one interactively in the REPL with /sessions (arrow-key picker, Enter to resume, Esc to cancel) — the stored transcript is replayed on resume so you see the whole conversation before continuing, and the session's kube context is restored so you're back on the same cluster
• Full-text search — kq --search "pod crash" or /search inside the REPL; FTS5-powered with highlighted match snippets and boolean syntax
• Conversation branching — /branch forks the current conversation at any point; the original is untouched; /branches lists all forks
• Token & cost tracking — every response shows tokens used; /tokens shows session totals and estimated dollar cost; rates configurable per model
• Human-in-the-Loop (HITL) — review and approve or deny destructive actions before they run
• Namespace context — set an active namespace with /ns <name>; it's injected into every message automatically
• File attachments — embed YAML, JSON, logs, and more with @filename anywhere in a message
• Conversation save — dump the full session to a Markdown file with /save
• Single-query mode — pipe-friendly with kq --query "…" and --output plain
• TLS & auth — --api-key / KUBE_Q_API_KEY env var, custom CA cert via --ca-cert
• Rich output — syntax-highlighted code blocks, elapsed response time, typo suggestions for slash commands
• Python SDK — use KubeQClient directly in your own scripts and tools
• Multi-backend — one CLI drives the kube-q server, direct OpenAI, or Azure OpenAI — selectable per launch with --backend or KUBE_Q_BACKEND
• Multi-cluster — switch kubectl context live with /context <name> (tab-completes from your kubeconfig); bundle cluster + backend + keys into named profiles under ~/.kube-q/profiles/ and launch with --profile <name>
• Plugins — drop a Python file in ~/.kube-q/plugins/ to register your own slash commands; loaded at REPL startup
• Web UI with live reconnect — browser terminal shows connection status, auto-reconnects with exponential backoff, and optional PTY_AUTH_TOKEN gate

Installation

pip install kube-q

Or from the Snap Store (Linux — bundles its own Python):

sudo snap install kubeintellect
sudo snap connect kubeintellect:dot-kube    # read ~/.kube (kubeconfig)
sudo snap connect kubeintellect:dot-kube-q  # read/write ~/.kube-q (config, sessions)
sudo snap alias kubeintellect.kq kq         # optional: the short command name

Both snap connect steps are required: strict confinement plus snapd's home interface excluding dot-directories means neither path is reachable without them.

Or via Homebrew:

brew tap MSKazemi/kube-q
brew install kube-q

On Homebrew 6.0+, brew tap may refuse this tap as untrusted (tap trust, added 6.0.0). Run brew trust --formula MSKazemi/kube-q/kube-q and retry.

Or install from source:

git clone https://github.com/MSKazemi/kubeintellect.git
cd kubeintellect/v4/packages/kube-q
pip install -e .

Requires Python 3.12+.

Quick start

# Start the interactive REPL (connects to https://api.kubeintellect.com by default)
kq

# Save your URL and API key once — takes effect immediately, persists across sessions
kq
/config set url=https://kube-q.example.com
/config set api_key=your-key-here

# Or pass them as flags for a one-off launch
kq --url https://kube-q.example.com --api-key your-key-here

# Single query and exit
kq --query "show me all pods in the default namespace"

# Pipe-friendly plain text output
kq --query "list failing deployments" --output plain

# List recent sessions
kq --list

# Search across all past conversations
kq --search "pod crash"

# Resume a previous session (shell) — replays the stored transcript
kq --session-id <id>

# Or pick one interactively inside the REPL (↑/↓, Enter to resume, Esc to cancel)
/sessions

In-REPL commands

Conversation

Namespace

Kubernetes context

Profiles & plugins

Session history

History & branching

FTS5 boolean syntax is supported: /search pods AND NOT staging

Connection & config

KEY accepts the full env-var name (KUBE_Q_URL) or the short alias (url).

/config set url=https://api.kubeintellect.com
/config set api_key=your-key-here
/config set model=kubeintellect-v2
/config reset api_key
/config

Token usage

Human-in-the-Loop

Keyboard shortcuts:

File attachments

Embed a file's contents directly in your message using @:

what is wrong with this deployment? @deployment.yaml
compare these two configs: @old.yaml @new.yaml
what is wrong here? @pod.yaml @service.yaml

Supports: yaml, json, py, sh, go, tf, toml, js, ts, rs, java, xml, html, md, txt, log, and more. Limit: 100 KB per file. Quote paths with spaces: @"my file.yaml".

CLI reference

kq [options]

Flags

Session history

kube-q saves every conversation to a local SQLite database at ~/.kube-q/history.db. Nothing is sent to or read from the server — this is a local-only mirror.

# See recent sessions
kq --list

# Resume from where you left off
kq --session-id <id>

# Search across everything you've ever discussed
kq --search "deployment rollback"
kq --search "pods AND crash"

Inside the REPL, /sessions, /history, /forget, /search, /branch, /branches, and /title give you full control over history.

Branching forks a conversation at the current message count. The original session is never modified — you get a new independent session you can take in a different direction. Branches show up in kq --list as regular sessions.

Token & cost tracking

After every response kube-q shows the token count in the footer:

kube-q  (1.2s · 460 tokens)

Use /tokens or /cost for a session summary:

┌─ Token Usage ─────────────────────────┐
│ This session:                         │
│   Prompt:     1,240 tokens            │
│   Completion: 3,890 tokens            │
│   Total:      5,130 tokens            │
│   Requests:   8                       │
│   Est. cost:  $0.0312                 │
│                                       │
│ Last response:                        │
│   120 in → 340 out ($0.0024)          │
└───────────────────────────────────────┘

Cost estimates are labeled "Est." — not exact. Built-in rates for kubeintellect-v2, gpt-4o, gpt-4o-mini, and claude-sonnet-4-6. Override for custom backends:

KUBE_Q_COST_PER_1K_PROMPT=0.002
KUBE_Q_COST_PER_1K_COMPLETION=0.008

If the server doesn't emit a usage block, the footer omits the token count — no errors, no noise.

Configuration

kube-q loads configuration from .env files and environment variables. Priority order (highest wins):

CLI flag  >  shell env var  >  ./.env  >  ~/.kube-q/.env  >  default

.env files

Shell-exported variables always win over .env files.

All supported variables

KUBE_Q_URL=https://api.kubeintellect.com
KUBE_Q_API_KEY=your-key-here
KUBE_Q_MODEL=kubeintellect-v2
KUBE_Q_TIMEOUT=120
KUBE_Q_HEALTH_TIMEOUT=5
KUBE_Q_NAMESPACE_TIMEOUT=3
KUBE_Q_STARTUP_RETRY_TIMEOUT=300
KUBE_Q_STARTUP_RETRY_INTERVAL=5
KUBE_Q_STREAM=true
KUBE_Q_OUTPUT=rich                  # rich | plain
KUBE_Q_LOG_LEVEL=INFO               # DEBUG | INFO | WARNING | ERROR
KUBE_Q_USER_NAME=You
KUBE_Q_AGENT_NAME=kube-q
KUBE_Q_COST_PER_1K_PROMPT=0.003    # override cost rate for /tokens
KUBE_Q_COST_PER_1K_COMPLETION=0.006

# ── Backend selection ─────────────────────────────────────────────────────────
KUBE_Q_BACKEND=kube-q              # kube-q | openai | azure
KUBE_Q_OPENAI_API_KEY=sk-...       # used when backend=openai
KUBE_Q_OPENAI_ENDPOINT=https://api.openai.com
KUBE_Q_OPENAI_MODEL=gpt-4o-mini
KUBE_Q_AZURE_OPENAI_API_KEY=...    # used when backend=azure
KUBE_Q_AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com
KUBE_Q_AZURE_OPENAI_DEPLOYMENT=my-gpt-4o
KUBE_Q_AZURE_OPENAI_API_VERSION=2024-06-01

# ── Multi-cluster ─────────────────────────────────────────────────────────────
KUBE_Q_CONTEXT=prod-cluster        # initial kubectl context (also set live via /context)
KUBE_Q_PROFILE=prod                # load ~/.kube-q/profiles/prod.env on top of defaults
KUBE_Q_PLUGIN_DIR=~/.kube-q/plugins  # override plugin directory

Example — per-cluster setup

# .env in your cluster's working directory
KUBE_Q_URL=https://kube-q.prod.example.com
KUBE_Q_API_KEY=prod-secret-key
KUBE_Q_USER_NAME=alice

Run kq from that directory and it picks up the settings automatically.

Quick one-time setup (pip users)

mkdir -p ~/.kube-q
cat >> ~/.kube-q/.env <<'EOF'
KUBE_Q_URL=https://kube-q.example.com
KUBE_Q_API_KEY=your-key-here
EOF

Multi-backend & multi-cluster

One kq binary drives three LLM backends and any number of Kubernetes clusters. Backends are chosen at launch; kubectl context switches live in the REPL; profiles bundle both together.

Backend selection

# kube-q server (default) — no extra config
kq

# Direct OpenAI — bypass the kube-q server entirely
kq --backend openai --openai-api-key sk-...

# Azure OpenAI — deployment-specific URL, api-key header
kq --backend azure \
   --azure-openai-api-key    ... \
   --azure-openai-endpoint   https://my-resource.openai.azure.com \
   --azure-openai-deployment gpt-4o

The backend is fixed for the lifetime of one REPL — switch by restarting with a different flag or profile. /state and the header panel show the active backend.

Kubernetes context (live, no restart)

/context prod-cluster      # Tab-completes from kubectl config get-contexts
/context                   # clear — no context prepended

The active context is prepended to every user message as [context: kube_context=X] so the backend knows which cluster to target. Set it at launch with --context prod-cluster or KUBE_Q_CONTEXT=prod-cluster.

Profiles (bundle backend + keys + context per environment)

Profiles live in ~/.kube-q/profiles/<name>.env and are loaded between ~/.kube-q/.env and ./.env when selected.

# Create a profile from a template
kq config profile new prod
# edit ~/.kube-q/profiles/prod.env — set KUBE_Q_BACKEND, KUBE_Q_CONTEXT, API keys, etc.

kq config profile list          # list profiles
kq config profile show prod     # dump a profile's contents
kq config profile delete staging

kq --profile prod               # launch with that profile
KUBE_Q_PROFILE=prod kq          # same, via env var

/profile                        # inside REPL: list profiles, show which is active

Profile switching requires a restart (the REPL shows the exact command for you).

Plugins (custom slash commands)

Any .py file in ~/.kube-q/plugins/ (or $KUBE_Q_PLUGIN_DIR) is auto-imported at REPL startup:

# ~/.kube-q/plugins/hello.py
from kube_q.plugins import register

@register("/hello", help="Say hello")
def hello(ctx):
    ctx.print(f"hi {ctx.cfg.user_name} — args: {ctx.args!r}")

ctx exposes args, state (the live SessionState), cfg (the current ReplConfig), print(text), and the Rich console. Use /plugins to list what's loaded. Plugins dispatch before the typo-catcher, so they always win.

Authentication

When the server has API key authentication enabled, requests without a valid key are rejected with HTTP 401. kube-q shows a clear message:

Authentication required. Set KUBE_Q_API_KEY or pass --api-key with a valid key.
Ask your administrator for an API key.

When auth is disabled on the server, no key is needed.

Human-in-the-Loop (HITL)

When the AI backend requests approval before executing a potentially destructive action, kube-q pauses:

╭─ Action requires approval ──────────────────╮
│ Action requires approval.                   │
│ Type /approve to proceed or /deny to cancel.│
╰─────────────────────────────────────────────╯
HITL> /approve

The prompt changes to HITL> while an action is pending. Type /approve to execute it or /deny to cancel.

Python SDK

kube_q.core exposes a typed SDK you can use directly in scripts, notebooks, or other tools — no CLI required.

from kube_q.core.client import KubeQClient
from kube_q.core.events import TokenEvent, FinalEvent

client = KubeQClient(url="http://localhost:8000", api_key="...")

# Non-streaming query
result = client.query("why are my pods failing?")
print(result["text"])

# Streaming — typed event objects
for event in client.stream("list all deployments in default namespace"):
    match event:
        case TokenEvent(data=d):
            print(d.content, end="", flush=True)
        case FinalEvent():
            break

All backend events are modelled as a typed Pydantic discriminated union in kube_q.core.events:

Web frontend

The web/ directory contains a Next.js web UI for kube-q.

Browser chat

Three-pane desktop layout (resizable panels):

• Chat panel — streaming markdown responses with react-markdown + syntax highlighting
• Reasoning timeline — live status, tool calls, and tool results as they happen
• Terminal panel — xterm.js view of tool execution output

Tabbed mobile layout, dark mode, and bearer-token auth gate included.

PTY terminal (full CLI in the browser)

The /pty route spawns kq in a pseudo-terminal via WebSocket. It's a pure byte relay — the Python CLI handles all logic; xterm.js renders it.

cd web
npm install
npm run dev:pty     # starts Next.js + pty-server on separate ports

Open http://localhost:3000/pty to get a full terminal running your local kq binary in the browser.

A coloured status dot in the toolbar shows the live connection state (connected, reconnecting…, error). If the WebSocket drops unexpectedly the terminal auto-reconnects with exponential backoff (up to 8 attempts, 1s → 15s).

To require a token before clients can spawn kq, set PTY_AUTH_TOKEN on the server and share it with users — they click the 🔑 Token button to enter it (stored in sessionStorage). Connections with a missing or wrong token are rejected with WebSocket close code 1008.

Data & privacy

• Session history is stored locally only at ~/.kube-q/history.db (SQLite). Nothing is sent to the kube-q server.
• Conversations may contain sensitive cluster data. Use /save with care — saved files go wherever you point them.
• The user ID (~/.kube-q/user-id) is stored with 0600 permissions.
• Logs are written to ~/.kube-q/kube-q.log (rotating, 5 MB × 3 files).