kmctl Reference

Command reference for the kmctl command-line tool.

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:

FlagShortDefaultDescription
--kubeconfig~/.kube/configPath to the kubeconfig file
--contextcurrent contextKubeconfig context to use
--namespace-nkubeconfig context namespace, else defaultKubernetes namespace
--clusterKubeconfig cluster override
--userKubeconfig user override
--asUsername to impersonate
--verbose-vPrint the underlying error after the message of a failed command (KMCTL_DEBUG=1 does the same)
--help-hShow 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 lineMeaning
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.

FlagDescription
--clientPrint only the client line; do not contact the cluster
--shortPrint only the kmctl version string, without contacting the cluster. Cannot be combined with -o
-o, --outputyaml, 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 Crew manifest and a CrewSchedulingPolicy that states what the crew needs from the cluster’s model catalog
  • A coordinator Agent and N specialist Agent resources (see --members)
  • PromptModule resources in ADL for the coordinator and each specialist
  • One Kubernetes MCPServer in read-only mode and the MCPGateway the agents reach it through
  • A namespaced Role and RoleBinding that allow get, list, and watch (see Access below)
  • A starter CrewFitnessSuite of 3 to 7 scenarios, all of which pass on a fresh install
  • A ConfigMap <name>-fitness holding the scenario files, so the deployed crew carries its scenarios (see Fitness scenarios below)
  • A README.md with 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.

FlagShortDescription
--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 NSpecialists 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-inputNever prompt; inputs not given as flags take their defaults
--output DIR-oDirectory to write scaffold output (default: .)
--contextKubeconfig context whose model catalog is checked for a model that can call tools (a global kmctl flag)
--chartLay 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:

--membersSpecialistsFitness scenarios
1workloads3
2workloads, events4
3workloads, events, networking5
4workloads, events, networking, config6
5the 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.

ColumnDescription
MODELThe model name on the server: the Ollama tag or the vLLM served name
SERVERThe ModelServer that offers it
SIZEsmall, medium, large, or unknown until the parameter count is known
ABILITIEStool-calling, reasoning, vision
CONTEXTThe context window in tokens
PRESENTno 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.

FlagDescription
--model-server NAMEThe model server that offers the model (required)
--parameters COUNTThe 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 LISTAbilities the model server cannot report: tool-calling, reasoning, vision. They replace what it reports
--dry-runSubmit 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.

FlagDescription
-fFile, directory, or - to read from stdin (required)
--dry-runValidate and print what would be applied without writing to the cluster
--forceForce 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.

FlagDefaultDescription
-ncontext namespaceNamespace of the crew
-o, --outputfullfull, plain, json, or quiet (see Output modes)
-q, --quietThe same as -o quiet: print only the answer. -q with a different -o is an error
--conversation-idContinue an existing conversation: its ID or a unique prefix of it
--idle-timeout5mStop waiting when the crew shows no activity for this long; 0 waits while the stream is open
--timeout0Overall 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

ModeWhat 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.
plainOne 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.
jsonNewline-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).
quietOnly 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.

FlagDescription
--scenarioRun only this named scenario as a single CrewFitness
-f, --filenameApply a CrewFitnessSuite manifest, then run it
--timeoutHow 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.

FlagShortDefaultDescription
-o FILE-o<suite>.xlsxFile path to write the downloaded XLSX
--dashboard-namespacekubemootNamespace where the Kubemoot dashboard is running
--dashboard-serviceemptyService 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.

FlagShortDefaultDescription
-n-nthe context’s namespaceNamespace of the crew
-o DIR-o./<crew>-memoryDirectory to write; it must not exist or be empty
--markdownoffAlso write the runtime projection as Markdown files
--originderived from namespace and crewOrigin id for the manifest
--allow-unscreenedoffExport facts that hold a credential. By default each fact whose value, topic or key matches a credential shape is left out
--nats-namespacenatsNamespace of the NATS Service
--nats-servicenatsName of the NATS Service
--nats-urlemptyConnect to this NATS URL instead of port-forwarding
--credsemptyNATS 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
FailureMessage
No kubeconfig or no current contextno Kubernetes cluster is configured (the kubeconfig has no current context)
--context not in the kubeconfigcontext "NAME" is not in the kubeconfig
API server unreachablecannot reach the Kubernetes API server (context "NAME")
Credentials rejectedthe 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 installedthe cluster does not serve the Kubemoot API (kubemoot.ai)
get of a missing objectno crew "NAME" in namespace "NS" (and the same for the other nouns)
Crew in another namespaceno crew "NAME" in namespace "NS"; found in "OTHER"
Gateway missing, not ready, or failingthe discussion gateway of crew "NAME" was not found in namespace "NS", ... is not ready, ... answered HTTP CODE
Stream cut before the answerthe discussion stream closed before the crew answered; the discussion may still finish
Bad flag or argumentscobra’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.