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:

-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).

kmctl version

kmctl version [--short]

Print the kmctl client version. With --short, prints only the version string.

Example:

kmctl version
# kmctl version v<version> (linux/amd64)

kmctl version --short
# v<version>

kmctl info

kmctl info [-o yaml|json]

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 a member count, offers a checkbox selection of discovered ollama providers, and lets you choose a model family (with a custom-entry and skip option). Pass --no-input with explicit flags to make it scriptable.

Output is written to <output>/<name>/ and includes:

• A Crew manifest, a CrewSchedulingPolicy, and the Model resources the crew selects from
• 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
    models.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.

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:

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
# Discovering providers...
# Display name [demo]: Demo Crew
# Members [2]: 3
# Providers: [x] ollama-gpu  [ ] ollama-gpu-b
# Model family [qwen]: qwen
# Writing demo/ ...done

Example (scripted):

kmctl create demo \
  --members 3 \
  --providers ollama-gpu,ollama-gpu-b \
  --model-family qwen \
  --no-input \
  -o /tmp/crews
# Wrote /tmp/crews/demo/

Example (as a Helm chart):

kmctl create demo --chart --members 2 --model-family qwen --no-input
# Scaffolded crew "demo" (2 tooler(s)) in ./demo:
#   demo/Chart.yaml
#   demo/values.yaml
#   demo/templates/crew.yaml
#   demo/templates/agents.yaml
#   demo/templates/promptmodules.yaml
#   demo/templates/models.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]

Inspect model provider resources and live GPU state.

kmctl model list

kmctl model list [-o <format>]

List all ModelProvider resources with connection status and basic metadata.

Example:

kmctl model list

kmctl model get

kmctl model get <name> [-o <format>]

Show details of a single model provider.

Example:

kmctl model get ollama-gpu -o yaml

kmctl model footprint

kmctl model footprint [-o <format>]

Show the resident Model resources per provider. This is the live GPU footprint view: which models are loaded, on which provider, and how much VRAM they occupy.

Example:

kmctl model footprint
# PROVIDER      MODEL            VRAM
# ollama-gpu    qwen3:32b        20.1 GiB
# ollama-gpu-b  qwen2.5:14b      8.7 GiB

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, ModelProvider, MCPServer, MCPGateway, RAGSource, KubemootConfig, CrewSchedulingPolicy, CrewFitnessSuite). Explicitly refuses non-kubemoot.ai kinds and directs you to kubectl apply for those.

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.

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>] [--quiet] [--conversation-id <id>]
kmctl conversation watch <crew> <conversation-id> [-n <namespace>]

Start a new conversation turn with a crew and stream the moot’s deliberation in real time. kmctl conversation reaches the crew’s discussion gateway through the Kubernetes API server’s service proxy using your kubeconfig credentials; no extra port-forwarding or networking setup is required.

kmctl conversation ask

kmctl conversation ask <crew> "<message>" [-n <namespace>] [--quiet] [--conversation-id <id>]

Starts a turn and streams discussion signals (agent evaluations, agreements, concerns) followed by the coordinator’s synthesis. When the turn completes, exits 0.

Example:

kmctl conversation ask homelab-pilot "what is failing?" -n crew-homelab-pilot

Sample output (streaming):

[evaluating] homelab-pilot-k8s-specialist
[evaluating] homelab-pilot-network-specialist
[agree]      homelab-pilot-k8s-specialist   "Three pods in CrashLoopBackOff..."
[agree]      homelab-pilot-network-specialist "DNS resolution failing for..."
[synthesis]  Two issues detected: (1) Pod homelab-pilot-backend is crash-looping
             due to a missing ConfigMap. (2) CoreDNS is returning SERVFAIL for
             in-cluster names in the homelab-pilot namespace.

With --quiet:

kmctl conversation ask homelab-pilot "what is failing?" -n crew-homelab-pilot --quiet
# Two issues detected: (1) Pod homelab-pilot-backend is crash-looping...

Continue an existing conversation:

kmctl conversation ask homelab-pilot "which ConfigMap is missing?" \
  -n crew-homelab-pilot \
  --conversation-id 7f3a1b9c

kmctl conversation watch

kmctl conversation watch <crew> <conversation-id> [-n <namespace>]

Live-tail an in-flight conversation thread. Prints each signal as it arrives and exits when the thread closes. Useful for watching a conversation that was started by another process (the dashboard, a CI job, or another terminal session).

Example:

kmctl conversation watch homelab-pilot 7f3a1b9c -n crew-homelab-pilot

Still planned in kmctl conversation

kmctl conversation list and kmctl conversation get are planned but not yet shipped. There is no gateway history endpoint yet. 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.

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 the Kubernetes API server’s service proxy, using your kubeconfig credentials. No extra port-forwarding is required.

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.

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.

Related pages

• kmctl - the CLI - overview and role in the ecosystem
• kmctl User Guide - install, quickstart, and shell completion
• Build a Crew - the resource-level workflow kmctl streamlines
• CrewForge - the VS Code extension that runs kmctl create --chart for its Create Crew command