On this page
#CLI and cluster lifecycle
Use the installed binary from any directory; a checkout and cargo run are not required. Inspect existing resources before creating, reusing, stopping or deleting them.
#Product command reference
kalisto pull --addons cni/cilium
kalisto up --workers 2 --addons cni/cilium
kalisto ls
kalisto --json ls
kalisto apply --name kalisto --manifest app.yaml
kalisto kubectl --name kalisto -- get nodes
kalisto status --name kalisto
kalisto kubeconfig --name kalisto
kalisto down --name kalisto
kalisto up --name kalisto
kalisto scale --name kalisto --workers 3
kalisto destroy --name kalisto
kalisto bench --runs 3 --workers 2 --addons cni/cilium
Treat this as a command reference, not an instruction to destroy a cluster or run a benchmark. scale --workers 3 requests three workers (plus the server), not three total nodes. Scale syntax is defined in the pinned CLI source.
down stops VMs but retains disks/state; installed workloads and VM-local data survive stop/resume. up resumes the saved backend/profile, including Firecracker artifact choices and SSH identities. Failed startup preserves definitions/disks: inspect status/logs and resume, rather than automatically deleting valuable state.
destroy irreversibly deletes the named cluster's state/disks. destroy --all / destroy -a delete all saved clusters and require explicitly authorized full cleanup. Prepared artifacts remain cached. Never infer deletion permission from a failed startup or port collision.
#Names, project configuration and ports
kalisto up \
--addons cni/cilium \
--project-root . \
--workers 0 \
--api-port 16443
--workers 0 starts a server-only profile. Use --backend or [cluster] backend = "lima" in kalisto.toml to select an alternative explicitly. Existing clusters retain their recorded backend; changing selection does not convert disks.
Agents/shared hosts should always pass explicit names and the matching kubeconfig instead of relying on mutable global selection. Concurrent clusters need different names and free --api-port values; the default API port is 16443. A distinct name alone does not avoid that conflict.
#Managed kubectl and manifests
kalisto apply --name kalisto --manifest app.yaml sends a user-supplied manifest to a running cluster. kalisto kubectl --name kalisto -- get nodes runs checksum-verified managed kubectl matching the cluster's Kubernetes/K3s version against its kubeconfig. pull prepares the binary; otherwise it can be fetched on first use, not during up. The standalone host kubectl command is not added to PATH.
With your own host client:
export KUBECONFIG="$(kalisto kubeconfig --name kalisto --path)"
kubectl get nodes
kubectl -n kube-system get pods
kubectl apply -f app.yaml
New application images may need registry access after startup. See workloads and explicit add-ons.
#Machine-readable inspection
Human-readable output is the default. The global --json flag emits machine-readable JSON for read-only list (ls), status, stats without --watch, and kubeconfig. Treat JSON field names as stable; non-JSON text is a convenience format, not an API.
#Progress and logs
Development source now uses indicatif progress bars and spinners for interactive preparation, cluster startup, worker joins, add-on rollout, manifest application and scaling. Item counts advance only after successful work; waits with no known total use a spinner, not an invented percentage. Applying a manifest does not claim that its workloads are Ready.
Progress uses stderr and keeps warnings and errors visible. Pipes, JSON inspection, CI and TERM=dumb use plain diagnostic output instead of animation. NO_COLOR removes colour. Explicit --log-level or RUST_LOG selection keeps ordinary logs; raw streamed runtime output and live k3s bootstrap logs require debug. The downloadable candidate and recordings are versioned separately; check their source revision before expecting development-source UI changes.
To inspect full diagnostics:
RUST_LOG=debug kalisto up --addons cni/cilium
RUST_LOG=warn kalisto bench --runs 3 --workers 2 --addons cni/cilium
The optional benchmark runs real lifecycle paths repeatedly and prints per-run timings. It is not equivalent to the functional three-node budget test, which checks authenticated API, all Cilium rollouts and both-worker DNS/cross-node traffic. Do not run benchmarks/live validation without the required explicit authorization.
#User-scoped files
config: ~/.config/kalisto
state: ~/.local/share/kalisto/clusters/<name>/
Reusable profiles live under artifacts/boot-v4 in Kalisto data; optional Lima disks/templates use artifacts/node-image, and Firecracker has its own versioned artifact cache. Private kubeconfigs/tokens/TLS manifests are not safe to publish.
#Troubleshooting without destructive fixes
- A missing/incompatible prepared profile means rerun
pullwith matching backend, architecture, K3s/Cilium versions and add-ons. Do not delete locks/caches automatically or expect online startup recovery. - No pod networking after bare
upis consistent with the no-CNI default; Cilium must be selected in both preparation and startup. Existing Helm-managed Cilium is not migrated in place. - An incompatible shared Apple daemon must not be stopped, replaced or reconfigured by Kalisto; use Lima explicitly or separately coordinate maintenance.
- For Apple helper connectivity after an upgrade, approve only required firewall helpers, not a disabled firewall.
- Check API port availability as well as cluster names before retrying.