kmctl - the CLI
kmctl (“kubemoot control”) is the command-line tool for working with crews and Kubemoot. It is the scriptable, terminal-native way to scaffold, apply, and exercise crews; CrewForge is the VS Code extension for developing crews and talking to them from the editor.
Status
kmctl is early and actively developed. It is installable from GitHub releases and
ships a working command set covering cluster inspection, crew scaffolding, resource
management, live conversation, fitness suite execution, and shell completion. Check
your installed version with kmctl version, and see the GitHub Releases page for the
latest. A small set of subcommands is still planned and marked as such in the
reference page.
The role it plays
A CLI fits the parts of the workflow that suit a terminal and scripts rather than a
GUI: working with crew manifests, driving Kubemoot from automation, and slotting into
CI/CD pipelines. Because everything Kubemoot manages is a Kubernetes resource, kmctl
is a convenience layer over those resources, not a separate control plane. The operator
remains the single source of lifecycle truth.
kmctl follows the kubectl / istioctl / helm convention in its flag and output
style. Standard kubeconfig discovery applies: --kubeconfig, --context,
-n/--namespace, and -A all work as you would expect. The standard auth flags
(--cluster, --user, --as, and so on) are also supported on every command.
What you can do with it
The shipped command surface covers eight areas:
Cluster and operator inspection. kmctl status checks that the cluster is
reachable and that the Kubemoot API group is registered. kmctl info reports the
resolved context, namespace, server URL, and server version. kmctl version prints
the client version.
Crew and agent inspection. kmctl crew list, kmctl crew get <name>,
kmctl agent list, and kmctl agent get <name> give a typed, readable view of what
is running, equivalent to kubectl get but without needing to know the CRD group and
version. Columns: Ready, Phase, Coordinator, Agents, Age (crew); Type, Ready, Phase,
Endpoint, Age (agent).
Crew scaffolding. kmctl create <name> scaffolds a complete, working crew: a
Crew manifest, a coordinator and 1 to 5 specialist Agents with PromptModules in ADL, a
read-only Kubernetes MCP server behind an MCPGateway, a CrewSchedulingPolicy, a starter
CrewFitnessSuite that passes on a fresh install, and a README. The crew is a read-only
guide to its own namespace; see The starter crew. It ships
no models and names no model server: its CrewSchedulingPolicy states what the crew needs,
and the scheduler matches that against the cluster’s model catalog. On a TTY it asks for
the display name and the number of specialists.
Pass --no-input with explicit flags to make it scriptable. Think of it like
helm create: the output is a starting point to customise, not a finished product.
Prompt and model inspection. kmctl prompt list and kmctl prompt get <name>
surface PromptModule resources. Use -o yaml to read the full ADL content.
kmctl model list shows the cluster’s model catalog: every model each model server
offers, with its size, abilities, and context window. Cluster owners add a model to the
catalog with kmctl model add. kmctl model server list and kmctl model server get <name>
show the model servers and what calibration measured. kmctl model footprint lists the
Model objects and their state on their model servers.
Manifest management. kmctl apply -f and kmctl delete are CRD-only
server-side-apply wrappers. They accept Crew, Agent, PromptModule, and the rest of
the Kubemoot API, and explicitly refuse non-kubemoot.ai resources, directing you to
kubectl apply for those. The operator’s finalizers handle cascading cleanup on
delete.
Live conversation. kmctl conversation ask <crew> "<message>" (alias conv)
starts a turn and streams the moot’s deliberation in real time, including each
specialist’s evaluation and the coordinator’s synthesis. Pass --quiet to print only
the final answer. Pass --conversation-id to continue an existing thread.
kmctl conversation watch live-tails an in-flight conversation by ID or a unique
prefix of one, kmctl conversation list lists a crew’s recent conversations, and
kmctl conversation workspace fetches an object from the discussion’s workspace. The command
reaches the crew’s discussion gateway through a port-forward to a ready pod behind its
Service, through the kubelet as kubectl port-forward does, using your kubeconfig
credentials. It needs no extra networking setup and works under a default-deny network
policy.
Fitness suite execution. kmctl fitness run <suite> (fitness has the alias fit) polls an
existing CrewFitnessSuite until every iteration has run, printing progress as it
goes; -f FILE applies a suite manifest first. Quality scores land after the
deferred judge pass, and the exit code reflects timeouts and API errors only. kmctl fitness list and kmctl fitness get <suite> inspect
suite status. kmctl fitness scenarios <suite> lists the scenarios in a suite.
Pass --scenario to run a single scenario in isolation as a quick smoke test.
kmctl fitness download <suite> retrieves the XLSX artifact for a completed suite
through a port-forward to a ready dashboard pod; use -o FILE to control the
output path.
Crew memory export. kmctl memory export <crew> writes the crew’s long-term memory
in the Open Memory Protocol Initiative (OMPI) interchange format, read-only, so you can
take a crew’s memory out with a command and no operator source.
Shell completion. kmctl completion bash|zsh|fish|powershell generates
completion scripts for all major shells. Resource names complete in get commands.
Still planned
kmctl conversation get, to read a past turn’s answer, is planned but not yet
shipped. A per-scenario score breakdown in
kmctl fitness get is also planned. To browse conversation history,
use the Kubemoot dashboard.
Install
See the kmctl User Guide for install steps, a runnable quickstart, and shell-completion setup. For the full command reference and flag details, see kmctl Reference.