Command API

This page describes command shapes used by the current app source. It is not a stable public API; it is a source-aligned reference for troubleshooting and audits.

ColimaStack resolves executable paths through tool lookup, injects the locator PATH, and redacts sensitive arguments/output before displaying command history.

Tool lookup and environment

Required binaries are searched in the process PATH plus:

/opt/homebrew/bin
/usr/local/bin
/opt/local/bin
/usr/bin
/bin
/usr/sbin
/sbin

For Docker and Kubernetes commands, the app forwards COLIMA_HOME, KUBECONFIG, DOCKER_HOST, DOCKER_CONTEXT, and proxy environment variables when present. Missing binaries become Diagnostics or backend issues.

Colima commands

All profile-scoped Colima commands set COLIMA_PROFILE=<profile>.

Purpose	Command shape	Mutates state
Profile list	colima list --json	No
Profile status	COLIMA_PROFILE=<profile> colima status --json	No
Start/create/apply profile	COLIMA_PROFILE=<profile> colima start [flags]	Yes
Stop profile	COLIMA_PROFILE=<profile> colima stop	Yes
Restart profile	COLIMA_PROFILE=<profile> colima restart	Yes
Delete profile	COLIMA_PROFILE=<profile> colima delete --force	Yes
Enable Kubernetes	COLIMA_PROFILE=<profile> colima kubernetes start	Yes
Disable Kubernetes	COLIMA_PROFILE=<profile> colima kubernetes stop	Yes
Update profile	COLIMA_PROFILE=<profile> colima update	Yes
Edit profile config	COLIMA_PROFILE=<profile> colima start --edit [--editor <editor>]	Yes
Template editor	COLIMA_PROFILE=<profile> colima template [--editor <editor>]	Yes
SSH config	`COLIMA_PROFILE= colima ssh-config [—layer=true	false]`
SSH access	`COLIMA_PROFILE= colima ssh [—layer=true	false] [— <command…>]`

colima start flags are generated from the profile editor when set:

--runtime <runtime>
--vm-type <vm-type>
--arch <architecture>
--cpus <count>
--memory <GiB>
--disk <GiB>
--mount-type <mount-type>
--mount <host[:vm][:w]>
--dns <server>
--env <KEY=VALUE>
--kubernetes=true|false
--kubernetes-version <version>
--network-address=true|false
--network-preferred-route=true|false
--port-forwarder <value>
--network-mode <mode>
--network-interface <interface>
--vz-rosetta
--nested-virtualization
--k3s-arg <arg>
--k3s-listen-port <port>

The UI blocks profile rename on edit and requires profile-name confirmation before delete.

Diagnostics commands

Purpose	Command shape	Notes
Colima version	colima version	Tool check
Docker client version	docker version --format "{{.Client.Version}}"	Tool check
kubectl client version	kubectl version --client=true -o json	Tool check
Lima version	limactl --version	Tool check
Docker context	docker context show	Runtime check
Docker server version	docker --context <expected-context> version --format "{{.Server.Version}}"	Used when selected profile is running and Docker runtime is expected
Kubernetes context	kubectl config current-context	Diagnostic message when kubectl is available

For the default profile, the expected Docker context is colima. For named profiles, it is colima-<profile>.

Docker commands

If a selected context is known, every Docker command is prefixed with docker --context <context>.

Inventory

View or metric	Command shape
Active context	docker context show
Containers	docker ps --all --no-trunc --format "{{json .}}"
Images	docker images --digests --no-trunc --format "{{json .}}"
Volumes	docker volume ls --format "{{json .}}"
Networks	docker network ls --no-trunc --format "{{json .}}"
Container stats	docker stats --no-stream --format "{{json .}}"
Disk usage	docker system df --format "{{json .}}"

Output is parsed as JSON lines. Malformed lines or records missing required fields are dropped with backend warnings. A dead container creates a warning issue.

Command details:

• External binary: docker.
• Timeout: 15 seconds.
• Mutating: no.
• Context behavior: --context <context> is added when the selected profile exposes one.
• Socket behavior: socket paths are displayed and indexed, but Docker inventory commands use context flags rather than passing socket paths.

Container controls

Container actions are routed through app command history and refresh the selected profile after a successful mutating action.

Purpose	Command shape	Mutates state
Start container	docker --context <context> start <container>	Yes
Stop container	docker --context <context> stop <container>	Yes
Restart container	docker --context <context> restart <container>	Yes
Pause container	docker --context <context> pause <container>	Yes
Resume container	docker --context <context> unpause <container>	Yes
Kill container	docker --context <context> kill <container>	Yes
Delete container	docker --context <context> rm <container>	Yes
Load logs	docker --context <context> logs [--timestamps] --tail <count> <container>	No
Load inspect JSON	docker --context <context> inspect <container>	No
Terminal command	docker --context <context> exec -it <container> /bin/sh	Depends on shell command

Command details:

• External binary: docker.
• Timeout: 30 seconds for lifecycle commands, logs, and inspect.
• Context behavior: --context <context> is added when the selected profile exposes one.
• Delete behavior: the UI requires typing the selected container name or ID exactly before rm can run.
• Output behavior: logs and inspect output are redacted before being stored in command history or shown in detail panels.

Feature pages: Containers, Images, Volumes, Networks, Monitor.

Kubernetes inventory commands

Kubernetes inventory is read-only. If a selected Kubernetes context is known, every command is prefixed with kubectl --context <context>.

View or metric	Command shape
Active context	kubectl config current-context
Nodes	kubectl get nodes -o json
Namespaces	kubectl get namespaces -o json
Pods	kubectl get pods --all-namespaces -o json
Services	kubectl get services --all-namespaces -o json
Deployments	kubectl get deployments --all-namespaces -o json
Node metrics	kubectl top nodes --no-headers
Pod metrics	kubectl top pods --all-namespaces --no-headers

Command details:

• External binary: kubectl.
• Timeout: 20 seconds.
• Mutating: no.
• Namespace behavior: pods, services, deployments, and pod metrics use --all-namespaces; nodes and namespaces are cluster-scoped.
• Metrics behavior: failed kubectl top commands create informational issues, not fatal errors.

Feature pages: Kubernetes, Workloads, Services.

Local files

Document	Path
Colima home	$COLIMA_HOME or ~/.colima
Profile config	$COLIMA_HOME/<profile>/colima.yaml
Default template	$COLIMA_HOME/_templates/default.yaml
SSH config	$COLIMA_HOME/ssh_config
Daemon log	$COLIMA_HOME/<profile>/daemon/daemon.log

See Security & Privacy for redaction, indexing, copy behavior, and stored output limits.