CLI Command Reference

Complete reference for all KAOS CLI commands.

Command Structure

kaos <subcommand> <action> [OPTIONS]

Subcommands:

• system - Operator and cluster management
• mcp - MCPServer management
• agent - Agent management
• modelapi - ModelAPI management
• ui - Web UI

---

kaos system

Operator installation and cluster management.

kaos system install

Install the KAOS operator.

kaos system install [OPTIONS]

Option	Short	Default	Description
--namespace	-n	kaos-system	Installation namespace
--release-name		kaos	Helm release name
--version		latest	Chart version
--set			Helm values
--wait		false	Wait for ready

kaos system uninstall

Uninstall the KAOS operator.

kaos system uninstall [OPTIONS]

kaos system status

Show cluster status.

kaos system status

Shows operator health, CRDs, resources, and gateway status.

kaos system runtimes

List registered MCP runtimes.

kaos system runtimes [OPTIONS]

Option	Short	Default	Description
--namespace	-n	kaos-system	Operator namespace

kaos system create-rbac

Generate RBAC YAML for MCPServer ServiceAccounts.

kaos system create-rbac [OPTIONS]

Option	Short	Description
--name	-n	ServiceAccount name (required)
--namespace	-ns	Namespace(s) to access
--read-only		Read-only permissions
--cluster-wide		ClusterRole instead of Role
--output	-o	Output file (default: stdout)

Example:

kaos system create-rbac --name k8s-mcp-sa --namespace my-ns > rbac.yaml
kubectl apply -f rbac.yaml

---

kaos mcp

MCPServer lifecycle management.

kaos mcp init

Scaffold a new FastMCP server project.

kaos mcp init [DIRECTORY] [OPTIONS]

Option	Description
--force	Overwrite existing files

Creates: server.py, requirements.txt, README.md

kaos mcp build

Build a Docker image from FastMCP server.

kaos mcp build [OPTIONS]

Option	Short	Default	Description
--name	-n	(required)	Image name
--tag	-t	latest	Image tag
--dir	-d	.	Source directory
--entry	-e	server.py	Entry point
--kind-load			Load to KIND cluster
--create-dockerfile			Generate Dockerfile
--platform			Docker platform

Example:

kaos mcp build --name my-mcp --tag v1 --kind-load

kaos mcp deploy

Deploy an MCPServer.

kaos mcp deploy [NAME] [OPTIONS]

Option	Short	Description
NAME		MCPServer name (auto-inferred from pyproject.toml)
--image	-i	Custom image
--runtime	-r	Registered runtime
--namespace	-n	Target namespace
--params	-p	Runtime parameters
--sa		ServiceAccount name

Examples:

# From custom image
kaos mcp deploy my-mcp --image my-image:v1

# From registered runtime
kaos mcp deploy slack-mcp --runtime slack

# Auto-infer from pyproject.toml
kaos mcp deploy

kaos mcp list

List MCPServers.

kaos mcp list [OPTIONS]

Option	Short	Default	Description
--namespace	-n	all	Filter by namespace
--output	-o	wide	Output format

kaos mcp get

Get MCPServer details.

kaos mcp get NAME [OPTIONS]

kaos mcp logs

View MCPServer logs.

kaos mcp logs NAME [OPTIONS]

Option	Short	Description
--follow	-f	Stream logs
--tail		Number of lines

kaos mcp invoke

Invoke an MCP tool.

kaos mcp invoke NAME [OPTIONS]

Option	Short	Description
--tool	-t	Tool name (required)
--args	-a	JSON arguments
--port	-p	Local port (default: 9000)

Example:

kaos mcp invoke echo-mcp --tool echo --args '{"message": "hello"}'

kaos mcp delete

Delete an MCPServer.

kaos mcp delete NAME [OPTIONS]

---

kaos agent

Agent lifecycle management.

kaos agent deploy

Deploy an Agent.

kaos agent deploy NAME --modelapi MODELAPI --model MODEL [OPTIONS]

Option	Short	Description
NAME		Agent name (required)
--modelapi	-a	ModelAPI reference (required)
--model	-m	Model name (required)
--namespace	-n	Target namespace
--instructions	-i	Agent instructions
--mcp		MCP server references (multiple)
--sub-agent		Sub-agent references (multiple)

Examples:

# Basic agent
kaos agent deploy my-agent --modelapi my-api --model gpt-4o

# With instructions and MCP tools
kaos agent deploy my-agent -a my-api -m gpt-4o -i "You are a helpful assistant" --mcp calculator

kaos agent list

List Agents.

kaos agent list [OPTIONS]

kaos agent get

Get Agent details.

kaos agent get NAME [OPTIONS]

kaos agent logs

View Agent logs.

kaos agent logs NAME [OPTIONS]

kaos agent invoke

Send a message to an Agent.

kaos agent invoke NAME [OPTIONS]

Option	Short	Description
--message	-m	Message (required)
--port	-p	Local port (default: 9001)
--stream	-s	Stream response

Example:

kaos agent invoke my-agent --message "Hello, how are you?"

kaos agent delete

Delete an Agent.

kaos agent delete NAME [OPTIONS]

---

kaos modelapi

ModelAPI lifecycle management.

kaos modelapi deploy

Deploy a ModelAPI.

kaos modelapi deploy NAME [OPTIONS]

Option	Short	Description
NAME		ModelAPI name (required)
--mode	-m	Mode: Proxy (LiteLLM) or Hosted (Ollama). Default: Proxy
--model		Model name (required for Hosted mode)
--namespace	-n	Target namespace

Examples:

# Deploy Proxy mode (LiteLLM)
kaos modelapi deploy my-api

# Deploy Hosted mode (Ollama)
kaos modelapi deploy my-api --mode Hosted --model smollm2:135m

kaos modelapi list

List ModelAPIs.

kaos modelapi list [OPTIONS]

kaos modelapi get

Get ModelAPI details.

kaos modelapi get NAME [OPTIONS]

kaos modelapi logs

View ModelAPI logs.

kaos modelapi logs NAME [OPTIONS]

kaos modelapi invoke

Send a chat completion request.

kaos modelapi invoke NAME [OPTIONS]

Option	Short	Description
--message	-m	Message (required)
--model		Model name (required)
--port	-p	Local port (default: 9002)

Example:

kaos modelapi invoke my-api --model gpt-4 --message "Hello"

kaos modelapi delete

Delete a ModelAPI.

kaos modelapi delete NAME [OPTIONS]

---

kaos ui

Start the KAOS web UI.

kaos ui [OPTIONS]

Option	Default	Description
--k8s-url	auto	Kubernetes API URL
--expose-port	8080	Local proxy port
--no-browser	false	Don't open browser

---

Environment Variables

Variable	Description
KUBECONFIG	Path to kubeconfig
KUBERNETES_SERVICE_HOST	In-cluster API host

Exit Codes

Code	Meaning
0	Success
1	Error

Common Workflows

Create and deploy custom MCP server

# 1. Scaffold project
kaos mcp init my-tools
cd my-tools

# 2. Edit server.py with your tools

# 3. Build and load to KIND
kaos mcp build --name my-tools --tag v1 --kind-load

# 4. Deploy
kaos mcp deploy my-tools --image my-tools:v1

Deploy Kubernetes MCP with RBAC

# 1. Generate RBAC
kaos system create-rbac --name k8s-sa --namespace default > rbac.yaml
kubectl apply -f rbac.yaml

# 2. Deploy
kaos mcp deploy k8s-tools --runtime kubernetes --sa k8s-sa