kmctl User Guide
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/configorKUBECONFIGenvironment variable). kubectlis not required bykmctlitself, 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 withkubectl 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
Related pages
- kmctl Reference - full command and flag reference
- kmctl - the CLI - overview and ecosystem role
- Build a Crew - resource-level crew authoring
- Define Fitness Functions - fitness suite authoring
- Develop a crew in VS Code - scaffolding,
deploying, testing, and redeploying a
--chartcrew from CrewForge instead of the terminal