Skip to content

v1.4.0 · stable release

kube-q — the KubeIntellect CLI

Talk to Kubernetes. In plain English.

kube-q is an AI-native terminal client for Kubernetes. Query, debug, and operate any cluster the way you think — with streaming answers, session memory, human-in-the-loop approvals, and a full browser REPL.

Get Started   View on GitHub  

:material-tag: v1.4.0 :material-language-python: Python 3.12+ :material-scale-balance: MIT License :material-lightning-bolt: Streaming SSE :material-docker: Docker Ready :material-database: SQLite History :material-shield-check: HITL Safe
0 minutes to first query
0 slash commands
0% local session history
0 kubectl flags to memorise

Why kube-q

A Kubernetes client that understands you

Stop context-switching between docs, cheat-sheets and your terminal. Ask a question, get an answer — with the evidence right there.

  • Plain-English Queries

    No more kubectl reference card. Ask "why are my pods crashing in production?" and get a structured, expert-level answer in seconds.

    CLI Reference

  • Persistent Session Memory

    Every conversation is saved locally in SQLite. Resume any past session, search across all history with full-text FTS5 queries, branch at any turn.

    Session History

  • Human-in-the-Loop Safety

    Before a destructive action runs, kube-q pauses and shows you the exact command, risk level and diff. You approve — or deny.

    HITL Guide

  • File Attachments

    Embed YAML manifests, logs, configs and more with @filename. The AI sees full file contents inline alongside your question.

    File Attachments

  • Browser Terminal

    The full kq REPL in any browser via Docker — xterm.js, WebSocket, node-pty. No duplicated logic. Every command, every stream, identical.

    Web UI

  • Token & Cost Tracking

    Every response shows token count and elapsed time. /tokens gives a full breakdown with estimated dollar cost, configurable per model.

    Token Tracking

  • Multi-Backend & Multi-Cluster

    One CLI, three backends: kube-q server, direct OpenAI, or Azure OpenAI — pick with --backend. Switch kubectl context live via /context, bundle cluster + keys into named profiles, add custom slash commands with plugins.

    Configuration

Install

Up and running in under a minute

Pick your flavour. One command and you're in.

pipx install kube-q
kq

pip install kube-q
kq

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

docker run -p 3000:3000 \
  -e KUBE_Q_URL=https://kube-q.example.com \
  -e KUBE_Q_API_KEY=your-key \
  ghcr.io/mskazemi/kube_q:latest

Open http://localhost:3000 for a full REPL in your browser.

Point at your backend

kq --url https://kube-q.example.com --api-key your-key
Or set it once in ~/.kube-q/.env and never type it again. See Configuration.

Live demo

Real conversation, real cluster

This is a verbatim kube-q session — from a vague question to a safe, approved fix.

kq — kube-q REPL · ns: production 
kube-q  v1.4.0  |  session abc123  |  ns: production
────────────────────────────────────────────────────

You> why are the pods in the payment service crashlooping?

kube-q> Investigating... ━━━━━━━━━━━━━━━━━━━━  (3 tool calls)

  The payment-service pods are in CrashLoopBackOff due to a missing
  environment variable: DATABASE_URL is not set in the deployment spec.

  The container exits immediately with:
    Error: required env DATABASE_URL is not set

  Fix:
  ┌─────────────────────────────────────────────────────────────┐
  │ kubectl set env deployment/payment-service \                │
  │   DATABASE_URL=postgres://db.prod.svc:5432/payments         │
  └─────────────────────────────────────────────────────────────┘

  (1.8s · 820 tokens)

You> apply the fix

kube-q> ╭─ Action requires approval ──────────────────────────╮
        │  kubectl set env deployment/payment-service \       │
        │    DATABASE_URL=postgres://db.prod.svc:5432/        │
        │                                                     │
        │  Risk: medium  ·  namespace: production             │
        │  Type /approve to proceed or /deny to cancel.       │
        ╰─────────────────────────────────────────────────────╯
HITL> /approve

kube-q> Done. Rollout triggered. Monitoring...
        All 3 pods are Running (45s).

Comparison

kube-q vs. raw kubectl

Both have their place — kube-q is built for the moments when you'd rather think out loud than recite syntax.

Capability raw kubectl kube-q
Natural-language queries ✗ ✓ streaming
Multi-resource root-cause analysis manual (logs + events + describe) ✓ automatic
Persistent session history shell history only ✓ SQLite + FTS5 search
Conversation branching ✗ ✓ /branch
Human-in-the-loop approvals ✗ ✓ for destructive ops
Token & cost accounting N/A ✓ per-response + session
Browser REPL ✗ ✓ Docker image
Python SDK client-go ✓ sync & async

How it works

Architecture at a glance

Everything runs through a streaming backend. Your cluster credentials never leave the server.

sequenceDiagram
    participant U as You
    participant K as kube-q CLI
    participant B as kube-q Backend
    participant C as Kubernetes Cluster

    U->>K: "why are my pods crashing in production?"
    K->>B: POST /chat (streaming SSE)
    B->>C: kubectl get pods, logs, events
    C-->>B: pod state, log tail, events
    B-->>K: token stream (real-time)
    K-->>U: rendered markdown answer
    note over K,U: HITL pause if destructive action detected

Built for

Use cases we've heard

From the first-time learner to the 3 AM on-call responder.

Incident response

First signal of trouble, you ask kube-q what changed. It correlates events, logs and recent rollouts so you stop hunting and start deciding.

Learning k8s

A junior engineer can ask "what does a readiness probe do for this pod?" and get an answer grounded in the actual manifest — not a blog post.

Safer rollouts

Destructive actions pause for an explicit /approve. Risk level and blast-radius are surfaced before anything touches the cluster.

/search "oom killed" walks every past session. Every investigation becomes institutional memory for the next one.

Scenario exploration

/branch forks a conversation the moment you want to try a different fix — without losing the original line of reasoning.

Automation & bots

Drive kube-q from a script or chatbot via the Python SDK. The same streaming, same HITL, same audit trail.

What's included

One project. Three surfaces.

Pick the interface that fits the moment — they all share the same backend and session store.

  • Terminal Client

    The kq command — a feature-rich interactive REPL built on prompt_toolkit with Tab-completion, command history, multi-line input, rich markdown rendering, and a full set of slash commands.

  • Python SDK

    Use KubeQClient (sync) or AsyncKubeQClient directly in scripts, notebooks, or your own tools — no CLI required. Full streaming and event-model support.

    SDK reference

  • Browser Terminal

    A Docker image that runs the full kq REPL in any browser via xterm.js + WebSocket + node-pty. Embeddable in iframes. Each tab is an isolated process.

    Web UI

kube-q turns the terminal into a conversation. The things I used to copy-paste from Stack Overflow — describe, get events, logs --previous, top pods — all just happen when I ask a question. It's the shortest path from "something's wrong" to "here's what and here's why." — The tool the author wishes they'd had on every 3 AM page.

Ready to try it?

Install in one command. Point at your backend. Start asking questions.

Quick Start   Star on GitHub