CLI

Use the CLI to start services, inspect pods, send turns, and manage a cluster. Cluster commands use your selected kubectl context and check managed targets before changes.

The polyc-cli crate ships a polychrome binary that targets whichever kubectl context is selected. There is no --context flag. Pick a context with kubectl config use-context.

Commands

Use doctor, init, and start to run locally. See the quickstart. Cluster management commands use your selected kubectl context.

Shell

# local stack (no cluster)
polychrome doctor                  # preflight: engine, free ports, disk, platform
polychrome init                    # write a config.toml pinned to this CLI version
polychrome start                   # bring the local stack up, print the API URL
polychrome stop                    # tear the local stack back down

# cluster lifecycle
polychrome up                      # apply manifests/overlays/<auto-detected>
polychrome status                  # pod readiness + AgentService health + Leases
polychrome ps                      # compact pod listing
polychrome logs control-plane -f   # tail control-plane logs
polychrome exec <pod> -- /bin/sh   # debug shell into a pod
polychrome restart --wait          # scale to 0 then re-apply, block until Ready
polychrome down                    # scale workloads to 0 (keeps PVC/config/RBAC)
polychrome down --delete           # full teardown (removes the namespace + PVC)
polychrome update                  # signature-verified self-update from GitHub Releases

# driving + inspecting conversations
polychrome send <conv-id> "hello" --idempotency-key <key>  # drive AgentService.Connect end-to-end
                                   #   (opens a port-forward; no manual kubectl)
polychrome conversation replay <id> --actor <admin-identity>
                                   #   replay a conversation's signed event log
polychrome usage                   # fleet-wide token usage rollup
polychrome usage --persona <id> --since 24h
                                   #   scoped to one persona, the last 24 hours

# live admin (no redeploy)
polychrome model get               # print the active provider/model selection
polychrome model set openai/llama3.2
                                   #   switch the LLM backend live (applies from the next turn)
polychrome add search --url <url>  # register an MCP connector (ToolService) at runtime
polychrome tools ls                # registered connectors: name, health, #tools

down scales Deployments to zero and preserves persistent volumes and configuration. Run up to restart those workloads. down --delete removes the namespace and persistent volumes, including their stored data.

Overlay auto-detection

up, down --delete, and restart pick the overlay from the context name: a bare default (k3s's stock context name) maps to k3s; polychrome-apple* (the Apple container micro-VM) and polychrome-linux* (bare k3s on the Linux host) both map to local-cluster; anything else maps to gke. The CLI rejects Docker-backed context names such as orbstack, kind-*, minikube, or k3d-* and directs you to scripts/cluster.sh up. Override detection with --overlay {k3s,local-cluster,gke} or --overlay-path <PATH>.

Wrong-cluster guard

Under --overlay auto, up, down, and restart reject contexts that resolve to gke. To change a managed cluster, select an explicit --overlay and pass --yes or confirm the cluster name. The CLI prints the context and API-server URL before making changes. It also rejects rendered overlays with unresolved placeholders such as REPLACE_DOMAIN.

polychrome send opens its own port-forward to AgentService and sends a framed Connect request. You do not need a separate kubectl port-forward command.