kmctl Reference
kmctl is the command-line tool for Kubemoot. It is a convenience layer over
Kubemoot’s Kubernetes resources, consistent in flag and output style with kubectl,
istioctl, and helm. The command layout (noun-first resource commands + global
manifest verbs) is a deliberate design choice; see
Command structure in the user guide.
This reference covers the shipped command surface. Commands marked planned are
designed but not yet implemented; all others work today. Check your installed version
with kmctl version. Every command has runnable --help examples, and get commands
offer shell completion of resource names. Run kmctl <command> --help for the same
information inline.
Global flags
These flags apply to every command:
| Flag | Short | Default | Description |
|---|---|---|---|
--kubeconfig | ~/.kube/config | Path to the kubeconfig file | |
--context | current context | Kubeconfig context to use | |
--namespace | -n | kubeconfig context namespace, else default | Kubernetes namespace |
--cluster | Kubeconfig cluster override | ||
--user | Kubeconfig user override | ||
--as | Username to impersonate | ||
--verbose | -v | Print the underlying error after the message of a failed command (KMCTL_DEBUG=1 does the same) | |
--help | -h | Show help for the command |
-A (--all-namespaces) and -o (--output) are not global. They belong to the commands that list or print resources, and their meaning varies by command (for example, -o is a directory for kmctl create and a file for kmctl fitness download).
Output formats
Commands that list or print resources take -o. The default is a table. -o yaml and -o json print the full object. -o kyaml prints KYAML, the strict YAML subset that kubectl get -o kyaml prints: every string is quoted, maps use { }, and lists use [ ]. KYAML is valid YAML, so any YAML parser reads it, and it removes the ambiguities of unquoted values such as no or on and of indentation.
kmctl crew get demo -o kyaml
-o kyaml works wherever a command accepts -o yaml. YAML stays the default.
kmctl version
kmctl version [--client] [--short] [-o yaml|json|kyaml]
Print kmctl’s own version and the Kubemoot release of the cluster it is connected to,
as a client line and a server line like kubectl version. The release comes from
status.release of the KubemootConfig the operator maintains, read through the
Kubernetes API with the active kubeconfig context. A build that was never stamped with a
release (a source build, or an unstamped chart) shows as development build.
Unlike kubectl version, the command exits 0 when the cluster cannot be reached or
reports no release. The client version is a complete answer on its own, so a script that
asks for it on a machine with no cluster still gets it; the server line, or
serverMessage with -o, says why there is no server version.
The server line gives the reason in the words kmctl uses for every other failure (see
Errors), and the client line is always printed:
| Server line | Meaning |
|---|---|
Kubemoot <release> | The operator reported its release |
unavailable (cannot reach the Kubernetes API server ...) | No cluster could be reached with this kubeconfig and context |
unavailable (no Kubernetes cluster is configured ...) | The kubeconfig has no current context |
unavailable (Kubemoot is not installed: no KubemootConfig named default) | The cluster has no such KubemootConfig |
unavailable (you are not allowed to get kubemootconfigs ...) | The credentials cannot read the KubemootConfig |
unavailable (the operator has not written its status yet) | The operator has not reconciled the object |
unavailable (this operator does not report a release; upgrade Kubemoot to see it) | The operator is older than the release field |
With -v or KMCTL_DEBUG=1 the server line also carries the underlying error
(; cause: ...), and serverCause appears with -o.
| Flag | Description |
|---|---|
--client | Print only the client line; do not contact the cluster |
--short | Print only the kmctl version string, without contacting the cluster. Cannot be combined with -o |
-o, --output | yaml, json, or kyaml: clientVersion and either serverVersion.release or serverMessage |
Example:
kmctl version
# Client Version: kmctl <version> (commit <commit>, built <date>)
# Server Version: Kubemoot <release>
kmctl version --short
# <version>
-o json with a release, and without one (serverMessage appears only when there is no
release):
{
"clientVersion": { "version": "<version>", "commit": "<commit>", "date": "<date>" },
"serverVersion": { "release": "<release>" }
}
{
"clientVersion": { "version": "<version>", "commit": "<commit>", "date": "<date>" },
"serverMessage": "cannot reach the Kubernetes API server (context \"<context>\")"
}
kmctl info
kmctl info [-o yaml|json|kyaml]
Print the resolved kubeconfig context, namespace, server URL, and server version.
Useful for confirming which cluster and namespace kmctl is pointed at before
running commands.
Example:
kmctl info
# Context: homelab
# Namespace: kubemoot
# Server: https://k8s.example.com:6443
# Version: v1.31.2
kmctl info -o yaml
kmctl status
kmctl status
Check cluster reachability and confirm that the Kubemoot API group
(kubemoot.ai) is installed. Exits non-zero if the cluster is unreachable or
Kubemoot is not registered.
Example:
kmctl status
# Cluster: reachable (v1.31.2)
# Kubemoot: installed (kubemoot.ai/v1alpha1)
kmctl create
kmctl create <name> [flags]
Scaffold a working crew directory. The output is a set of Kubemoot manifests ready
to review, customise, and apply with kmctl apply -f. Think of it like helm create’s
nginx chart: a small, complete example that works on a fresh install, to change into your
own crew.
The scaffolded crew is the starter crew: a read-only guide to the Kubernetes namespace it is installed into. Ask it what is running, what is wrong, and why; it reads the namespace with real tools and answers from what it found. It never changes anything. See The starter crew for what it contains and a walkthrough.
<name> is the crew’s technical name and becomes the Kubernetes name of its objects. It
must be a DNS-1123 label: lowercase letters, digits, and hyphens, starting and ending with a
letter or digit, at most 36 characters. The operator names objects after the crew, and the
longest is the tool index Service <crew>-kubernetes-mcp-tools-query, which must fit a
63-character DNS label (and the name stays under Helm’s 53-character release-name limit).
--display-name sets the name people read.
On a TTY, kmctl create runs interactively: it asks for the display name first (default:
<name>), then the number of specialists. Pass --no-input with explicit flags to make it
scriptable.
Models. The crew ships no Model objects and names no model server. Its
CrewSchedulingPolicy states what the crew needs: every phase requires a model that can
call tools (capability/tool-calling: "true"), mulling ranks the allowed models by
qualityBias (which reads the kubemoot.ai/size label), and triage sets preferFaster: 50
to favor the model calibration measured fastest. The scheduler matches those rules against
the cluster’s model catalog, so the same crew installs on any
cluster with a model that can call tools. Scaffolding needs no cluster. When the current
cluster can be read, kmctl create reads its catalog and warns when no model in it can call
tools; such a crew applies Ready but stays Unschedulable until a model server offers one.
See kmctl model list.
Output is written to <output>/<name>/ and includes:
- A
Crewmanifest and aCrewSchedulingPolicythat states what the crew needs from the cluster’s model catalog - A coordinator
Agentand N specialistAgentresources (see--members) PromptModuleresources in ADL for the coordinator and each specialist- One Kubernetes
MCPServerin read-only mode and theMCPGatewaythe agents reach it through - A namespaced
RoleandRoleBindingthat allow get, list, and watch (see Access below) - A starter
CrewFitnessSuiteof 3 to 7 scenarios, all of which pass on a fresh install - A ConfigMap
<name>-fitnessholding the scenario files, so the deployed crew carries its scenarios (see Fitness scenarios below) - A
README.mdwith a “first five minutes” guide, titled with the display name and noting “Its Kubernetes name is<name>”
With --chart, the same manifests are laid out as a Helm chart instead of loose YAML:
demo/
Chart.yaml
values.yaml
templates/
crew.yaml
agents.yaml
promptmodules.yaml
tools.yaml
rbac.yaml
fitness-scenarios.yaml
fitness/
fitness.yaml
README.md
The fitness suite is kept in fitness/, outside templates/, so helm install never
starts a run on its own; apply it yourself when you want one. This is the layout
CrewForge scaffolds when you use New Kubemoot Crew Here,
and the layout its Crew Sources view expects a chart source to have.
| Flag | Short | Description |
|---|---|---|
--display-name "..." | The name people read: any one line of text, no line breaks, tabs, or control characters, at most 100 characters (default: <name>). Stored as the kubemoot.ai/display-name annotation | |
--members N | Specialists beside the coordinator, 1 to 5 (default: prompted interactively). Size 1 is workloads; each larger size adds the next of events, networking, config, and reviewer | |
--no-input | Never prompt; inputs not given as flags take their defaults | |
--output DIR | -o | Directory to write scaffold output (default: .) |
--context | Kubeconfig context whose model catalog is checked for a model that can call tools (a global kmctl flag) | |
--chart | Lay the crew out as a Helm chart (Chart.yaml, templates/, fitness/) instead of loose manifests |
Display name. --display-name is stored as the annotation kubemoot.ai/display-name on
the Crew (in crew.yaml, or templates/crew.yaml for a chart) and, with --chart, in the
annotations of Chart.yaml. The README.md title is the display name. Text containing
{{ is written safely for Helm: it is rendered verbatim and never executed. Tools such as
CrewForge show the display name and fall back to the
Kubernetes name when the annotation is absent.
Fitness scenarios. The scaffold deploys the crew’s scenarios as a ConfigMap, so a
running crew carries them. In chart mode, templates/fitness-scenarios.yaml builds the
ConfigMap <name>-fitness from the files in fitness/ (.Files.Glob "fitness/*"), labeled
kubemoot.ai/crew: <name> and kubemoot.ai/fitness-kind: scenarios. In bundle mode, the
same ConfigMap is written to access/fitness-scenarios.yaml; apply it with
kubectl apply -n <ns> -f access/ beside the RBAC, because kmctl apply takes only
kubemoot.ai kinds. A ConfigMap starts nothing: installing the crew still never starts a
run. CrewForge lists and runs a live crew’s scenarios from this ConfigMap.
Scope. The synthesis-prompt module has a scope component switched by the chart value
access.clusterWide. By default (false) the crew reads only its own namespace; answers
name it (“in namespace X”) and never describe “your cluster”. When true, it reads the
whole cluster read-only without Secrets and names the namespace of each resource. Asked
about other namespaces or the whole cluster, a namespace-scoped crew says its access is
limited to its namespace, that setting access.clusterWide: true in values.yaml and
redeploying widens it, and answers only what its namespace shows. For a bundle, scaffold as
a chart with --chart and set the value. The scaffolded README.md has a “What it can
read” section.
Sizes. --members counts specialists, so the crew has that many plus the coordinator:
--members | Specialists | Fitness scenarios |
|---|---|---|
| 1 | workloads | 3 |
| 2 | workloads, events | 4 |
| 3 | workloads, events, networking | 5 |
| 4 | workloads, events, networking, config | 6 |
| 5 | the four above (Toolers) plus reviewer (Analyst) | 7 |
Each Tooler reads one slice of the namespace: workloads (Pods, Deployments, ReplicaSets,
StatefulSets, Jobs), events (Warning events, restarts, recent failures), networking
(Services, endpoints, Ingresses or HTTPRoutes, NetworkPolicies), and config (ConfigMaps,
ServiceAccounts, and the Secrets that pod specs reference). The reviewer checks the answer
against the data the Toolers gathered and flags unsupported claims.
Access. The tool server runs with --read-only and a namespaced Role that grants only
get, list, and watch. The Role has no Secret access: Kubernetes cannot grant a Secret’s
name without its data, so the config specialist names Secrets from the references in pod
specs. Set access.clusterWide: true in the chart’s values.yaml to use a ClusterRole and
let the crew read every namespace; it stays read-only and still has no Secret access.
Limits. The prompts carry the namespace name, which Helm fills in at install, so a
rendered bundle is tied to its namespace. The reviewer cannot see Tooler findings over 4 KB,
which the Toolers post as artifact pointers.
Example (interactive):
kmctl create demo
# Display name, the name people read (any text): Demo Crew
# How many specialists beside the coordinator (1-5)? 3
# Scaffolded crew "demo" (3 specialist(s) beside the coordinator) in ./demo: ...
Example (scripted):
kmctl create demo \
--members 3 \
--no-input \
-o /tmp/crews
# Scaffolded crew "demo" (3 specialist(s) beside the coordinator) in /tmp/crews/demo: ...
Example (as a Helm chart):
kmctl create demo --chart --members 2 --no-input
# Scaffolded crew "demo" (2 specialist(s) beside the coordinator) in ./demo:
# demo/Chart.yaml
# demo/values.yaml
# demo/templates/crew.yaml
# demo/templates/agents.yaml
# demo/templates/promptmodules.yaml
# demo/templates/tools.yaml
# demo/templates/rbac.yaml
# demo/templates/fitness-scenarios.yaml
# demo/fitness/fitness.yaml
# demo/README.md
#
# Next: helm upgrade --install demo demo --namespace demo --create-namespace
Example (with a display name):
kmctl create homelab-health-guide --display-name "Homelab Health Guide"
# Scaffolded crew "Homelab Health Guide" (homelab-health-guide) ...
kmctl crew
kmctl crew <subcommand> [flags]
Inspect Crew resources.
kmctl crew list
kmctl crew list [-n <namespace>] [-A] [-o <format>]
List all Crew resources. Default table columns: Name, Namespace, Ready, Phase,
Coordinator, Agents, Age.
Example:
kmctl crew list -A
# NAME NAMESPACE READY PHASE COORDINATOR AGENTS AGE
# demo kubemoot true Running demo-coordinator 3 2d
kmctl crew get
kmctl crew get <name> [-n <namespace>] [-o <format>]
Show details of a single Crew. With -o yaml, prints the full CR including status.
Example:
kmctl crew get demo
kmctl crew get demo -o yaml
kmctl agent
kmctl agent <subcommand> [flags]
Inspect Agent resources.
kmctl agent list
kmctl agent list [-n <namespace>] [-A] [-o <format>]
List all Agent resources. Default table columns: Name, Namespace, Type, Ready,
Phase, Endpoint, Age.
Example:
kmctl agent list -n kubemoot
# NAME NAMESPACE TYPE READY PHASE ENDPOINT AGE
# demo-coordinator kubemoot coordinator true Running ... 2d
# demo-specialist-0 kubemoot specialist true Running ... 2d
kmctl agent get
kmctl agent get <name> [-n <namespace>] [-o <format>]
Show details of a single Agent, including scheduling status and model assignment.
Example:
kmctl agent get demo-specialist-0
kmctl agent get demo-specialist-0 -o yaml
kmctl prompt
kmctl prompt <subcommand> [flags]
Inspect PromptModule resources.
kmctl prompt list
kmctl prompt list [-n <namespace>] [-A] [-o <format>]
List all PromptModules. Default table columns: Name, Namespace, Order, Age.
Example:
kmctl prompt list -n kubemoot
kmctl prompt get
kmctl prompt get <name> [-n <namespace>] [-o <format>]
Show a PromptModule. Use -o yaml to read the full ADL content of the module.
Example:
kmctl prompt get demo-coordinator-prompt -o yaml
kmctl model
kmctl model <subcommand> [flags]
Read the cluster’s model catalog and its model servers. Crews ship no models; they select from the catalog by label. See the model catalog.
kmctl model list
kmctl model list [-n <namespace>] [-o <format>]
List the cluster’s model catalog, one row per model per model server, as each ModelServer
reports it in status.models. It reads the model servers in every namespace, or only the
namespace -n names; -o yaml|json|kyaml prints the entries as a list.
| Column | Description |
|---|---|
MODEL | The model name on the server: the Ollama tag or the vLLM served name |
SERVER | The ModelServer that offers it |
SIZE | small, medium, large, or unknown until the parameter count is known |
ABILITIES | tool-calling, reasoning, vision |
CONTEXT | The context window in tokens |
PRESENT | no for a model the cluster owner asked for that the server does not have yet |
When no model in the catalog can call tools, it warns: a crew that requires one, as every
crew kmctl create scaffolds does, applies Ready but stays Unschedulable until a model
server offers one.
Example:
kmctl model list
# MODEL SERVER SIZE ABILITIES CONTEXT PRESENT
# qwen3:14b vllm-gpu medium tool-calling 40960 yes
# qwen3:8b ollama-gpu small reasoning,tool-calling 40960 yes
kmctl model add
kmctl model add <model> --model-server <name> [--parameters <count>] [--capabilities <list>] [--dry-run]
Add a model to the cluster’s model catalog: the cluster owner’s command. It writes a
Model into the namespace of the model server --model-server names. <model> is the name
requests use: the Ollama tag (qwen3:14b) or the vLLM served name. On an Ollama model server
the operator downloads the model. A vLLM model server serves what it was started with; add
its models to say what they are.
The Model is named after the model server and the model, such as ollama-gpu-qwen3-14b-<hash>,
with a short hash added when the model name holds characters a Kubernetes name cannot. Adding
the same model again updates it. Without -n, the model server must be in exactly one
namespace. kmctl model list shows the entry once the operator has merged it.
| Flag | Description |
|---|---|
--model-server NAME | The model server that offers the model (required) |
--parameters COUNT | The total parameter count, such as 14B or 0.5B, which sets the size class: small under 12B, medium from 12B to under 30B, large from 30B. A vLLM model server cannot report it |
--capabilities LIST | Abilities the model server cannot report: tool-calling, reasoning, vision. They replace what it reports |
--dry-run | Submit a server-side dry run without persisting |
Examples:
kmctl model add qwen3:14b --model-server ollama-gpu
kmctl model add qwen3-14b --model-server vllm-gpu --parameters 14B --capabilities tool-calling,reasoning
kmctl model add qwen3:8b --model-server ollama-gpu --dry-run
kmctl model server list
kmctl model server list [-n <namespace> | -A] [-o <format>]
List the ModelServer resources: NAME, TYPE, ENDPOINT, READY, CALIBRATION (the
calibration phase), and AGE.
kmctl model server get
kmctl model server get <name> [-o <format>]
Show one model server and what calibration measured, one row per model.
Example:
kmctl model server get ollama-gpu
# Calibration: Calibrated, measured 2 of 2 models, engine <version>, completed <time>
#
# MODEL FITS LOAD GENERATE PROMPT PARALLEL MEMORY REASON
# qwen3:14b yes 2.5s 86 tok/s 6313 tok/s 2 x 162 tok/s 13839 MiB
# qwen3:8b yes 3.1s 152 tok/s 11748 tok/s 2 x 241 tok/s 9475 MiB
kmctl model footprint
kmctl model footprint [-n <namespace> | -A] [-o <format>]
List the Model objects and their state on their model servers: NAME, SERVER, MODEL,
STATE, SIZE, and AGE.
Example:
kmctl model footprint -A
kmctl apply
kmctl apply -f <file|dir|-> [flags]
Apply Kubemoot CRD manifests using server-side apply. Accepts a file, a directory,
or - for stdin. Accepts only kubemoot.ai resources (Crew, Agent, PromptModule,
Model, ModelServer, MCPServer, MCPGateway, RAGSource, KubemootConfig,
CrewSchedulingPolicy, CrewFitnessSuite). Explicitly refuses non-kubemoot.ai kinds
and directs you to kubectl apply for those.
| Flag | Description |
|---|---|
-f | File, directory, or - to read from stdin (required) |
--dry-run | Validate and print what would be applied without writing to the cluster |
--force | Force apply even if field manager conflicts exist |
Examples:
kmctl apply -f demo/
kmctl apply -f demo/ --dry-run
kmctl apply -f - < crew.yaml
kmctl delete
kmctl delete <kind> <name> [-n <namespace>]
kmctl delete -f <file|dir>
Delete a Kubemoot CRD resource. Accepts only kubemoot.ai kinds. The operator’s
finalizers handle cascading cleanup; kmctl delete does not implement its own
lifecycle logic.
Examples:
kmctl delete crew demo -n kubemoot
kmctl delete -f demo/
kmctl completion
kmctl completion <shell>
Generate shell completion scripts. Supported shells: bash, zsh, fish,
powershell.
Completing a conversation ID (kmctl conversation watch <crew> <Tab>) lists the crew’s
recent conversations, so each press opens a short port-forward to the crew’s gateway. It is
a little slower than completing a name kmctl reads from the Kubernetes API, and it needs the
same permissions as kmctl conversation.
Examples:
# bash - add to ~/.bashrc
source <(kmctl completion bash)
# zsh - add to ~/.zshrc
source <(kmctl completion zsh)
# fish
kmctl completion fish > ~/.config/fish/completions/kmctl.fish
# PowerShell - add to $PROFILE
kmctl completion powershell | Out-String | Invoke-Expression
See the kmctl User Guide for full setup instructions per shell.
kmctl conversation
Alias: conv
kmctl conversation ask <crew> "<message>" [-n <namespace>] [-o full|plain|json|quiet] [-q] [--conversation-id <id>]
kmctl conversation watch <crew> <conversation-id> [-n <namespace>] [-o full|plain|json|quiet] [-q]
kmctl conversation list <crew> [-n <namespace>] [-o yaml|json|kyaml]
kmctl conversation placements <crew> <conversation-id> [-n <namespace>] [-o table|yaml|json|kyaml] [--timeout <duration>]
kmctl conversation workspace <crew> <key> [-n <namespace>] [-f <file>]
Start a conversation turn with a crew and stream the moot’s deliberation in real
time. kmctl conversation reaches the crew’s discussion gateway by opening a
port-forward to a ready pod behind its Service, through the kubelet as
kubectl port-forward does, using your kubeconfig credentials. You do not run a
port-forward yourself, and the connection works under a default-deny network policy
with no cluster-specific policy.
Permissions, in the namespace of the Service: get on services, list on pods, and
create on pods/portforward. A missing permission is reported with the verb and
resource that were refused.
kmctl conversation ask
kmctl conversation ask <crew> "<message>" [-n <namespace>] [-o full|plain|json|quiet] [-q] [--conversation-id <id>]
Starts a turn and streams the discussion until the crew answers, then exits 0.
| Flag | Default | Description |
|---|---|---|
-n | context namespace | Namespace of the crew |
-o, --output | full | full, plain, json, or quiet (see Output modes) |
-q, --quiet | The same as -o quiet: print only the answer. -q with a different -o is an error | |
--conversation-id | Continue an existing conversation: its ID or a unique prefix of it | |
--idle-timeout | 5m | Stop waiting when the crew shows no activity for this long; 0 waits while the stream is open |
--timeout | 0 | Overall cap on the wait, for scripts; 0 means no cap |
ask sends this machine’s IANA time zone and local date and time with each question (timeZone and localDateTime in the request to the crew’s discussion gateway), so the crew’s tools resolve “today”, “recent”, and “upcoming” to your date even when the cluster runs in another time zone. kmctl reads the zone from TZ, then /etc/localtime, then /etc/timezone. When none names a known zone it sends the local date and time alone, and a crew without either falls back to its configured default zone.
Example:
kmctl conversation ask homelab-pilot "Describe the proxmox nodes." -n crew-homelab-pilot -o plain
conversation 6733c361-aa0c-4bde-85c6-e143af23b251
[ 2.0s] thread t-42
[ 3.0s] subcommittee: pilot-metrics, pilot-proxmox, pilot-storage; brief: List each Proxmox node with its role...
[ 8.0s] pilot-gpu stood aside (qwen3:8b, 419 tokens): not in the subcommittee
[ 10.0s] pilot-proxmox agree (evaluation 10.4s, qwen3:14b, 5,850 tokens): The cluster has three Proxmox nodes, all online.
[ 11.0s] pilot-metrics agree (evaluation 12.0s, qwen3:14b, 8,230 tokens): attached artifact (8.3 KB); fetch command below
[ 14.0s] done
ANSWER:
## Proxmox nodes
...
**How this answer was made**
- Total time (as received by kmctl): 14.0s; first signal after 8.0s
- Crew time (thread start to answer, as the crew published): 31.0s
- Subcommittee: 3 convened (pilot-metrics (node metrics), pilot-proxmox (proxmox inventory), pilot-storage)
- Agents: 4 took part (pilot-proxmox, pilot-metrics, pilot-gpu, pilot-storage); 1 stood aside (pilot-gpu)
- Signals: 2 agree, 1 failure, 1 stand_aside
- Tokens: 15,740 in, 2,059 out
- Models: qwen3:14b, qwen3:8b
- Tool errors: pilot-storage: zfs_pool_status failed 3 times: connection refused
- Workspace object from pilot-metrics (8.3 KB): `kmctl conversation workspace homelab-pilot crew-homelab-pilot/homelab-pilot/t-42/pilot-metrics/agree-1b2c -n crew-homelab-pilot`
Next: kmctl conversation ask homelab-pilot "<next question>" -n crew-homelab-pilot --conversation-id 6733c361-aa0c-4bde-85c6-e143af23b251
Continue the conversation with a short ID prefix:
kmctl conversation ask homelab-pilot "and their memory?" -n crew-homelab-pilot --conversation-id 6733c
Output modes
| Mode | What it shows |
|---|---|
full (default) | A live view: one row per agent with a spinner while it works, its step, the accelerator and model it runs on, its step durations and tokens, and the subcommittee under the header. Each row settles to a colored signal. The answer is rendered as markdown. |
plain | One line per event with the time since the turn began, no color or animation, for logs, CI, and screen readers. The answer is raw markdown. |
json | Newline-delimited JSON: a conversation line, one line per gateway event (with elapsedMs and any step duration added), and a final result line with answer, summary, and next. Every line carries schemaVersion (1). |
quiet | Only the answer. -q is the same. |
full falls back to plain when stdout is not a terminal, NO_COLOR is set, or
TERM=dumb.
Every mode except quiet ends with a summary right after the answer’s own notes,
then the follow-up command. The summary has the total time and the time to the
first signal (as kmctl received them), the crew’s own time from the thread’s start
to the answer, the subcommittee the coordinator convened with each agent’s reason
when given, the agents that took part and stood aside, signals by kind, tokens in
and out, accelerators, models, agents that waited for accelerator capacity, tool errors,
and the command that fetches each attached artifact. Step durations come from the
timestamps the crew published (summary.timeSource is published); with a
discussion gateway that does not send timestamps they are measured on receipt
(received), and the fields that gateway does not send (tokens, models, the
subcommittee, tool errors) are left out rather than estimated. Retries are not
published by the crew, so the summary does not show them. The stream’s events and
fields are described in
Conversations, Turns, and Threads.
How long kmctl waits
kmctl waits as long as the crew is working. While anyone on the crew is busy, the
gateway sends an activity event every 15 seconds: plain prints it as a busy:
line, json as a line of type activity, and full names who is busy in the
header. The only default clock is --idle-timeout (default 5m), which runs only
while the crew shows no activity and starts again with every event from the crew.
--timeout (default 0, no cap) is an overall limit for scripts. When either one
stops the wait, kmctl prints the conversation and thread IDs and the command that
reattaches, because the crew may still answer:
Error: the crew showed no activity for 5m0s; the discussion may still finish.
Conversation 6733c361-aa0c-4bde-85c6-e143af23b251, thread 8f0c2a1e
Reattach: kmctl conversation watch homelab-pilot 6733c361-aa0c-4bde-85c6-e143af23b251 -n crew-homelab-pilot
kmctl conversation watch
kmctl conversation watch <crew> <conversation-id> [-n <namespace>] [-o full|plain|json|quiet] [-q]
Follow the discussion of a conversation’s current turn until the crew answers, for
example one started by the dashboard, a CI job, or another terminal. The
conversation ID may be a unique prefix. The output modes and the wait flags
(--idle-timeout, --timeout) are the same as for ask.
kmctl conversation watch homelab-pilot 6733c -n crew-homelab-pilot
kmctl conversation list
kmctl conversation list <crew> [-n <namespace>] [-o yaml|json|kyaml]
List the crew’s recent conversations, newest first, with each one’s first question. The gateway reads them from the discussion stream, which keeps about a day.
kmctl conversation list homelab-pilot -n crew-homelab-pilot
# CONVERSATION ID LAST TURN TURNS FIRST QUESTION
# 6733c361-aa0c-4bde-85c6-e143af23b251 2026-10-15T09:12:40Z 2 Describe the proxmox nodes.
kmctl conversation placements
kmctl conversation placements <crew> <conversation-id> [-n <namespace>] [-o table|yaml|json|kyaml] [--timeout <duration>]
Show where the scheduler placed each model call of the conversation’s latest turn and
why. It reads the receipt that the crew’s coordinator puts on the turn’s closing
message (see Reading a placement decision),
so the discussion gateway must forward the receipt on its closing event. A turn that has
closed replays from the discussion stream; for a turn still running the command waits
until it closes, up to --timeout (default 2 minutes). The conversation ID may be a
unique prefix.
The table has one row per call: the agent, the phase, the model and accelerator it
ran on as model@server, the policy that placed it (learned, algorithm or
shadow), the predicted and the measured time, and the error, measured minus
predicted, so positive means the call took longer than predicted. Below it, each call
gives the reason for its placement and the other servers the scheduler weighed, with
their predicted times. The last line counts the calls per policy and gives the mean
absolute error over the calls that have a prediction.
kmctl conversation placements homelab-pilot 6733c -n crew-homelab-pilot
# # AGENT PHASE PLACEMENT POLICY PREDICTED ACTUAL ERROR
# 1 coordinator advisory qwen3:14b@ollama-gpu learned 2.9s 3.4s +500ms (15%)
# 2 kubernetes-specialist evaluation qwen3:14b@ollama-gpu (cold) algorithm 11.4s 13.8s +2.4s (17%)
-o json, -o yaml and -o kyaml print conversationId, crew, calls (the calls
exactly as the receipt carried them) and summary. A receipt without placement calls
prints one line saying so, and calls is an empty list in the structured formats.
Short conversation IDs and completion
Wherever kmctl takes a conversation ID, a unique prefix works, as with git hashes.
An ambiguous prefix fails and lists the matching conversations with their first
questions; a prefix that matches no recent conversation says so. A full ID is used
as given. Shell completion of --conversation-id and of watch’s conversation
argument offers the crew’s recent conversations, each with its first question as
the description. A discussion gateway that cannot list conversations needs the full
ID, and kmctl says so.
kmctl conversation workspace
kmctl conversation workspace <crew> <key> [-n <namespace>] [-f <file>]
Write an object from the discussion’s workspace (a stored
tool result, or a contribution too large for the stream) to stdout, or to a file with
-f. The conversation output prints this command for each stored object. The
coordinator deletes a thread’s workspace objects soon after the thread closes; after that
kmctl reports the object as not found. kmctl conversation artifact is the old name of
the command: it still works for one release, prints a warning on stderr, and is then
removed. kmctl asks the gateway’s /workspace route and falls back to the old /artifact
route on a gateway that does not have it. In -o json, objects are under workspace and
workspaces; the old artifact and artifacts keys carry the same content for one release.
Still planned in kmctl conversation
kmctl conversation get, to read a past turn’s answer, is planned but not yet
shipped. To browse conversation history, use the
Kubemoot dashboard.
kmctl fitness
Alias: fit
kmctl fitness list [-n <namespace>] [-A]
kmctl fitness get <suite> [-n <namespace>]
kmctl fitness scenarios <suite> [-n <namespace>]
kmctl fitness run <suite> [-n <namespace>] [--scenario <name>] [--timeout <duration>]
kmctl fitness download <suite> [-n <namespace>] [-o FILE]
Inspect and run CrewFitnessSuite resources. kmctl fitness run polls to
phase=Completed, which the operator sets when every iteration has run. Phase
reflects execution, not test outcome: a suite whose iterations failed their
assertions still reaches Completed. The deferred judge pass runs after that;
status.judge reports its progress and scores, and kmctl fitness get shows them.
kmctl fitness list
kmctl fitness list [-n <namespace>] [-A]
List all fitness suites. Default table columns: Name, Namespace, Phase, Done, Total, Passed, Failed, Judge (the judge phase), Quality (the mean judge score, 0 to 100), Age.
Example:
kmctl fitness list -A
# NAMESPACE NAME PHASE DONE TOTAL PASSED FAILED JUDGE QUALITY AGE
# kubemoot demo-starter Completed 10 10 9 1 Complete 82 3h
# kubemoot nightly Running 4 20 4 <none> Pending <none> 12m
kmctl fitness get
kmctl fitness get <suite> [-n <namespace>] [-o <format>]
Show a suite’s results, read from its status through the Kubernetes API: the
summary row, the judge state, and one row per scenario with its iteration
outcomes, mean duration, judge score, and the judge’s reason (one line, up to
200 characters). Use -o yaml for the full object. See
Results in status for the fields.
Example:
kmctl fitness get demo-starter
# NAME PHASE DONE TOTAL PASSED FAILED JUDGE QUALITY AGE
# demo-starter Completed 10 10 9 1 Complete 82 3h
#
# Judge: Complete, 2 of 2 scenarios judged, mean 82, completed 2026-10-02T14:31:07Z
#
# SCENARIO ITERATIONS PASSED FAILED ERRORED MEAN DURATION SCORE REASON
# smoke-hello 5 5 0 0 42s 90 Names both nodes and their roles.
# gotcha-dns 5 4 1 0 1m3s 74 Correct resolver; omits the search domain.
kmctl fitness get demo-starter -o yaml
kmctl fitness scenarios
kmctl fitness scenarios <suite> [-n <namespace>]
List the scenarios (testRefs) defined in a suite, showing each scenario name and its current result if the suite has run.
Example:
kmctl fitness scenarios demo-starter
# SCENARIO RESULT
# smoke-hello passed
# concept-routing passed
# gotcha-dns failed
kmctl fitness run
kmctl fitness run <suite> [-n <namespace>] [--scenario <name>] [--timeout <duration>]
Run a suite and wait for completion. Polls progress and prints it as the run
proceeds. It returns once the iterations have finished (or the suite is
cancelled) and exits 0 whatever their outcome, which kmctl fitness get shows; it
exits non-zero on a timeout or an API error. When the judge has
not finished scoring the run by then, it says so, and kmctl fitness get shows the
judge’s progress and scores.
Until the judge pass finishes, kmctl fitness download serves a provisional
workbook whose quality scores are 0; once judging completes, the operator rewrites
the workbook with the final scores. An iteration Job that fails is retried twice
before the iteration is recorded as failed.
To run a single scenario in isolation, pass --scenario. This creates a single
CrewFitness for that scenario rather than running the full suite.
| Flag | Description |
|---|---|
--scenario | Run only this named scenario as a single CrewFitness |
-f, --filename | Apply a CrewFitnessSuite manifest, then run it |
--timeout | How long to wait for completion (default: 30m) |
Example (full suite):
kmctl fitness run demo-starter -n kubemoot
# Running demo-starter (10 scenarios)...
# [1/10] smoke-hello passed (42s)
# [2/10] concept-routing passed (1m 3s)
# ...
# Result: 9 passed, 1 failed
Example (single scenario smoke test):
kmctl fitness run demo-starter --scenario smoke-hello -n kubemoot
# Running smoke-hello...
# Result: passed (38s)
kmctl fitness download
kmctl fitness download <suite> [-n <namespace>] [-o FILE] [--dashboard-namespace NS] [--dashboard-service SVC]
Download the XLSX artifact for a completed suite. The command fetches the artifact
from the dashboard’s artifact endpoint through a port-forward to a ready dashboard pod,
using your kubeconfig credentials. You do not run a port-forward yourself. It needs get
on services, list on pods, and create on pods/portforward in the dashboard’s
namespace.
The suite must have reached phase=Completed before the artifact is available. A workbook downloaded before the judge pass finishes is provisional and carries quality 0.
| Flag | Short | Default | Description |
|---|---|---|---|
-o FILE | -o | <suite>.xlsx | File path to write the downloaded XLSX |
--dashboard-namespace | kubemoot | Namespace where the Kubemoot dashboard is running | |
--dashboard-service | empty | Service name of the Kubemoot dashboard; when empty, the Service is discovered by label in --dashboard-namespace |
Example:
kmctl fitness download demo-starter -n kubemoot
# Downloads to demo-starter.xlsx
kmctl fitness download demo-starter -o results.xlsx -n kubemoot
# Downloads to results.xlsx
Re-judging a run
kmctl has no re-judge command. A CrewFitnessSuite with a spec.rejudge block scores an
earlier run’s saved answers against the suite’s current scenarios without asking the crew;
apply it with kmctl fitness run -f FILE or kubectl apply, then use kmctl fitness get and
kmctl fitness download as for any suite. See
Re-judge an earlier run.
Still planned in kmctl fitness
kmctl fitness download still fetches the XLSX through the dashboard. Fetching it
through an operator-owned API instead is planned.
kmctl memory
Commands for a crew’s long-term memory (the facts it learned, see Agent context).
kmctl memory export
kmctl memory export <crew> [-n <namespace>] [-o <dir>] [--markdown] [--origin ID] [--allow-unscreened]
[--nats-url URL] [--creds FILE] [--nats-namespace NS] [--nats-service SVC]
Write the crew’s memory in the interchange format of the Open Memory Protocol
Initiative (OMPI) exchange-and-runtime working spec v0.6: manifest.json and one JSON
memory object per fact under memories/. With --markdown it also writes each fact as
a Markdown file under markdown/. The mapping is the one the operator’s ompi-export
uses; see Agent context for what maps and what
does not.
The command only reads. Crew memory lives in a NATS key-value bucket, and the NATS server is not an HTTP service the Kubernetes API server can proxy, so kmctl opens a port-forward to a ready pod of the NATS Service with your kubeconfig credentials, lists the bucket’s keys and gets the values it needs, and closes the forward. It never writes, deletes or touches a fact. An unreachable server or a missing bucket is an error; only a crew with no facts gives an export with none. Every document is checked against the schema before anything is written, and the directory is written atomically.
| Flag | Short | Default | Description |
|---|---|---|---|
-n | -n | the context’s namespace | Namespace of the crew |
-o DIR | -o | ./<crew>-memory | Directory to write; it must not exist or be empty |
--markdown | off | Also write the runtime projection as Markdown files | |
--origin | derived from namespace and crew | Origin id for the manifest | |
--allow-unscreened | off | Export facts that hold a credential. By default each fact whose value, topic or key matches a credential shape is left out | |
--nats-namespace | nats | Namespace of the NATS Service | |
--nats-service | nats | Name of the NATS Service | |
--nats-url | empty | Connect to this NATS URL instead of port-forwarding | |
--creds | empty | NATS credentials file, for a server that needs them |
Each entry that could not be turned into a fact is printed with its reason, and the
manifest says selection instead of snapshot. A fact whose value, topic or key holds a
credential (a bearer or basic token, an API
key, a token or password assignment, a JSON Web Token, a cloud access key, or a long
hexadecimal string, a private key header, a password in a URL) is left out the same way,
never printed as text, because the spec says credentials must not be exported as memory.
A credential in the value is listed with the shape it matched. A credential in the topic
or key is found with the strict redaction, and the fact is listed by an opaque id
(<namespace>.<crew>.#<id>, a truncated one-way hash of the store key) so the key does
not print it. The screen does not flag
ordinary words such as “basic authentication”, content digests, or a bare commit hash,
but it matches shapes, so a fact that only looks like a credential can be left out.
--allow-unscreened turns the screen off: the export then holds every fact as stored,
credentials included, so check it before you share it.
Example:
kmctl memory export homelab-pilot -n crew-homelab-pilot -o ./pilot-memory --markdown
# left out "crew-homelab-pilot.homelab-pilot.ops.login": its value holds a credential (key, token, secret or password assignment); not exported as memory
# wrote 11 memory object(s) of crew-homelab-pilot/homelab-pilot to ./pilot-memory
kmctl memory export homelab-pilot -n crew-homelab-pilot -o ./pilot-raw --allow-unscreened
# wrote 12 memory object(s) of crew-homelab-pilot/homelab-pilot to ./pilot-raw
Errors
When a command fails, kmctl prints what went wrong and, on a second line, what to do
next, and exits with status 1:
$ kmctl conversation ask homelab-pilot "List the pods in the system namespace."
Error: no crew "homelab-pilot" in namespace "default"; found in "crew-homelab-pilot"
Hint: Pass -n crew-homelab-pilot
| Failure | Message |
|---|---|
| No kubeconfig or no current context | no Kubernetes cluster is configured (the kubeconfig has no current context) |
--context not in the kubeconfig | context "NAME" is not in the kubeconfig |
| API server unreachable | cannot reach the Kubernetes API server (context "NAME") |
| Credentials rejected | the Kubernetes API server did not accept your credentials (context "NAME") |
| Missing permission (RBAC) | you are not allowed to VERB RESOURCE in namespace "NS" |
| Kubemoot not installed | the cluster does not serve the Kubemoot API (kubemoot.ai) |
get of a missing object | no crew "NAME" in namespace "NS" (and the same for the other nouns) |
| Crew in another namespace | no crew "NAME" in namespace "NS"; found in "OTHER" |
| Gateway missing, not ready, or failing | the discussion gateway of crew "NAME" was not found in namespace "NS", ... is not ready, ... answered HTTP CODE |
| Stream cut before the answer | the discussion stream closed before the crew answered; the discussion may still finish |
| Bad flag or arguments | cobra’s message, then the command’s usage line |
When a crew is not in the namespace, kmctl looks for a crew of that name in every
namespace and names the ones it finds. Without permission to list crews across the
cluster, it suggests -n and kmctl crew list -A instead. -n always decides the
namespace; kmctl never switches it on its own.
kmctl version is the one command that does not fail on a cluster error: it explains the
failure with the same messages as the table above, in its server line (or serverMessage
with -o), prints the client version, and exits 0. See kmctl version.
-v (--verbose) or KMCTL_DEBUG=1 adds a third line, Cause:, with the error from
the Kubernetes client underneath. The Error: and Hint: labels are colored only when
stderr is a terminal, NO_COLOR is unset, and TERM is not dumb.
Related pages
- kmctl - the CLI - overview and role in the ecosystem
- kmctl User Guide - quickstart and shell completion; install kmctl from the release
- Build a Crew - the resource-level workflow
kmctlstreamlines - CrewForge - the VS Code extension that runs
kmctl create --chartfor its Create Crew command