Operator CLI

One binary drives the whole cluster — bring it up, watch it, shell in, send a turn, tear it down — without hand-writing kubectl invocations. It acts on your selected kubectl context and fails closed before touching a production target.

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

doctor, init, and start are the fastest path to a working conversation on a laptop — see the quickstart. Everything else acts on your selected kubectl context.

  # 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"  # drive AgentService.Connect end-to-end
                                     #   (opens a port-forward; no manual kubectl)
> polychrome enroll <routine> --provider slack --user <id>
                                     #   start a routine-join enrollment, print the link
> polychrome conversation replay <id>
                                     #   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 is non-destructive by default: it scales every Deployment to zero, so up brings the stack back in seconds with the event log and config intact. down --delete is the real teardown — treat it as "remove this for good".

Overlay auto-detection

up, down --delete, and restart pick the overlay from the context name: orbstack, kind-*, minikube, and k3d-* map to local; a bare default (k3s's stock context name) maps to k3s; polychrome-apple* (the Apple container micro-VM) maps to apple; anything else maps to gke. Override with --overlay {local,k3s,apple,gke} or --overlay-path <PATH>.

Wrong-cluster guard

Because the CLI acts on the current context, up/down/restart fail closed on a managed (production) target: under --overlay auto a context that resolves to gke is refused outright. To mutate a managed cluster on purpose, pass an explicit --overlay plus --yes (or type the cluster's name when prompted); the tool echoes the context and API-server URL before it acts. It also refuses to apply an overlay whose render still contains build-time placeholders (for example, REPLACE_DOMAIN) — a template is not an apply target.

polychrome send opens its own port-forward to AgentService and frames a Connect request for you, so you can drive a full turn against a running cluster without touching kubectl port-forward by hand.