kmctl User Guide

Install kmctl, scaffold and deploy your first crew, and set up shell completion.

kmctl is the command-line tool for Kubemoot. This guide covers installation, a runnable quickstart that walks through the core workflow, and shell-completion setup.

For the complete command reference, see kmctl Reference. For an overview of kmctl’s role in the ecosystem, see kmctl - the CLI.


Command structure

kmctl uses a hybrid noun-verb layout, chosen deliberately as the best fit for a domain CLI with deeply-nested resources and actions that have no clean kubectl equivalent.

Resource commands are noun-first and scoped: kmctl crew list, kmctl crew get, kmctl fitness run, kmctl conversation ask. This means kmctl <noun> --help shows a clean, focused list of what you can do to that resource, and shell completion scales as the surface grows.

Cross-cutting actions are global verbs that parallel kubectl conventions: kmctl create, kmctl apply -f, kmctl delete, kmctl status, kmctl version. This is intentional: kubectl muscle memory applies exactly where it helps (applying and deleting manifests), while resource-specific actions such as ask, run, and scenarios live where they are discoverable.

This hybrid layout follows the same convention as istioctl, helm, and Knative’s kn, which is the consensus pattern for developer-facing tools that combine manifest management with domain-specific commands. A flat verb-first model (like kubectl get <type>) would not house these domain actions cleanly and would fracture discoverability as the surface grows.


Install

Binary releases

Install the latest release, with its checksum and signature checks, from the kmctl README. It covers Linux, macOS, and Windows on amd64 and arm64; the commands live there so they are kept in one place. Then check the install with kmctl version.

Homebrew (planned)

brew install kubemoot/tap/kmctl

Status: planned. The Homebrew tap ships in a later distribution phase.

Krew (planned)

kubectl krew install kmctl

Status: planned. The krew manifest ships in a later distribution phase.


Prerequisites

  • A Kubernetes cluster with the Kubemoot operator installed and running.
  • A kubeconfig with access to the cluster (standard ~/.kube/config or KUBECONFIG environment variable).
  • kubectl is not required by kmctl itself, but the same kubeconfig is used.

Quickstart

This walkthrough covers the core workflow end to end: confirm the cluster is ready, scaffold a crew, apply it, inspect the result, start a conversation, and run a fitness suite.

1. Confirm the cluster is ready

kmctl status

Expected output:

Cluster:  reachable (v1.31.2)
Kubemoot: installed (kubemoot.ai/v1alpha1)

If Kubemoot: not installed appears, the operator is not yet deployed. See Installation.

Check which cluster and namespace kmctl is pointed at:

kmctl info

2. Scaffold a crew

kmctl create demo

demo is the crew’s Kubernetes name: lowercase letters, digits, and hyphens, starting and ending with a letter or digit, at most 36 characters. To give the crew a name people read, add --display-name "Demo Crew"; it defaults to the Kubernetes name.

On a TTY, kmctl create runs interactively: it asks for the display name and how many specialists the crew has. Answer the prompts and it writes a demo/ directory:

demo/
  crew.yaml
  agents.yaml
  promptmodules.yaml
  tools.yaml
  access/
    rbac.yaml
    fitness-scenarios.yaml
  fitness/
    fitness.yaml
  README.md

The result is the starter crew: a read-only guide to the namespace it is installed into. --members (1 to 5) sets how many specialists it has.

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, mulling ranks the allowed models with qualityBias, and triage favors the model calibration measured fastest. The scheduler matches those rules against the cluster’s model catalog, so the same crew installs on any cluster that has a model that can call tools. Scaffolding needs no cluster; when the current cluster’s catalog has no such model, kmctl create warns. See the catalog with:

kmctl model list

To skip interaction in CI or scripts, supply the inputs as flags:

kmctl create demo \
  --members 2 \
  --no-input

To scaffold the same crew as a Helm chart instead (Chart.yaml, templates/, and a fitness/ folder kept outside templates/ so installing it never starts a run on its own), add --chart:

kmctl create demo --chart --members 2 --no-input

A chart deploys with helm upgrade --install demo demo --namespace demo --create-namespace instead of the kubectl and kmctl apply steps below; both forms scaffold the same manifests. This is the form CrewForge scaffolds with New Kubemoot Crew Here, and the layout its Crew Sources view expects a chart source to have; see Develop a crew in VS Code for that workflow.

3. Review and customise

Open the generated directory. Key files:

  • crew.yaml - the Crew resource and its CrewSchedulingPolicy, which states what each phase needs from the model catalog.
  • agents.yaml - the coordinator and the specialist Agents; review each agent’s capabilities.
  • promptmodules.yaml - the PromptModules in ADL; this is the main place to shape the crew’s discussion behaviour.
  • tools.yaml - the read-only Kubernetes MCP server and the MCPGateway in front of it.
  • access/rbac.yaml - the Role the tool server runs with; apply it first with kubectl apply -n <namespace> -f access/.
  • fitness/fitness.yaml - a starter CrewFitnessSuite of scenarios that ground on the crew’s own pods.

See Build a Crew and Write Agents and ADL for guidance on what to customise and how.

4. Apply to the cluster

kmctl create prints the command that deploys what it scaffolded. For the loose-manifest form, with the default namespace crew-demo:

kubectl create namespace crew-demo && \
  kubectl apply -n crew-demo -f ./demo/access && \
  kmctl apply -n crew-demo -f ./demo

The access/ folder holds the Role the tool server runs with, so it applies first, with kubectl. kmctl apply uses server-side apply, accepts only Kubemoot CRD resources, and reads the files directly in the directory it is given, not subdirectories. That is why access/ and fitness/ are separate steps. Add --dry-run to preview what kmctl apply would write.

5. Watch the crew come up

kmctl crew get demo -n crew-demo
kmctl agent list -n crew-demo

6. Ask the crew

kmctl conversation ask demo "List the pods in this namespace and their status." -n crew-demo

kmctl conversation reaches the crew by opening a port-forward to a ready pod of the crew’s discussion gateway Service, so you do not run kubectl port-forward yourself. Your kubeconfig identity needs get on services, list on pods, and create on pods/portforward in the crew’s namespace. Add --quiet to print only the final answer, and --conversation-id <id> (the ID the first ask prints) to continue the same conversation.

ask also sends this machine’s time zone and local date and time with the question, so the crew’s tools use your date and not the date where the cluster runs. 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.

7. Run the fitness suite

kmctl fitness run -f ./demo/fitness/fitness.yaml -n crew-demo
kmctl fitness scenarios demo-starter -n crew-demo
kmctl fitness get demo-starter -n crew-demo

kmctl fitness run returns when every iteration has run (phase=Completed). Quality scores land after the judge pass; kmctl fitness get shows them once they are in. Then download the workbook:

kmctl fitness download demo-starter -n crew-demo

The starter crew walks through this flow end to end, including how to change one rule and ask again.


Shell completion

kmctl completion generates completion scripts for bash, zsh, fish, and 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.

bash

# Add to ~/.bashrc or ~/.bash_profile:
source <(kmctl completion bash)

To install system-wide for all users:

kmctl completion bash | sudo tee /etc/bash_completion.d/kmctl

zsh

# Add to ~/.zshrc:
source <(kmctl completion zsh)

If you use Oh My Zsh, save the completion file to the custom completions directory:

kmctl completion zsh > "${fpath[1]}/_kmctl"

fish

kmctl completion fish | source
# For persistence across sessions:
kmctl completion fish > ~/.config/fish/completions/kmctl.fish

PowerShell

# Add to $PROFILE:
kmctl completion powershell | Out-String | Invoke-Expression

Common patterns

Use a specific namespace

kmctl crew list -n my-namespace
kmctl agent list -n my-namespace

Use a specific kubeconfig context

kmctl --context staging crew list
kmctl --context staging info

Non-interactive scaffolding for CI

kmctl create my-crew \
  --members 3 \
  --no-input \
  -o /workspace/crews

Scaffold as a Helm chart

kmctl create my-crew --chart --display-name "My Crew" --members 2 --no-input
helm upgrade --install my-crew my-crew --namespace my-crew --create-namespace

Preview what apply would do

kmctl apply -f my-crew/ --dry-run

See the model catalog

kmctl model list

Add a model to the catalog

A cluster owner adds a model to the catalog with kmctl model add, which writes a Model into the namespace of the model server that offers it. On an Ollama model server the operator downloads it; for a vLLM model server, declare what the server cannot report:

kmctl model add qwen3:14b --model-server ollama-gpu
kmctl model add qwen3-14b --model-server vllm-gpu --parameters 14B --capabilities tool-calling,reasoning

Inspect the Model objects and their state

kmctl model footprint

Read a PromptModule’s ADL content

kmctl prompt get my-coordinator-prompt -o yaml

Ask a crew a question

kmctl conversation ask homelab-pilot "what is the cluster status?" \
  -n crew-homelab-pilot

Continue a conversation thread

kmctl conversation ask homelab-pilot "can you be more specific?" \
  -n crew-homelab-pilot \
  --conversation-id <id>

Run a fitness suite and wait for completion

kmctl fitness run my-suite -n kubemoot

Smoke-test a single scenario

kmctl fitness run my-suite --scenario smoke-hello -n kubemoot

Download a fitness suite XLSX artifact

kmctl fitness download my-suite -n kubemoot
# Downloads to my-suite.xlsx

kmctl fitness download my-suite -o results.xlsx -n kubemoot

List fitness suites across all namespaces

kmctl fitness list -A

Inline help

Every command has a --help flag that mirrors this reference:

kmctl --help
kmctl crew --help
kmctl create --help
kmctl conversation --help
kmctl fitness --help