>poco

The polypoint cloud companion. GKE pods, local stacks, builds, databases and vaults — one CLI, one TUI, every environment.

v0.2.3 preview v0.3.0-preview.6
install — macOS & Linux
$ curl -fsSL https://get-poco.polypoint.dev | bash

Needs an authenticated gcloud with your polypoint Google account — that's the whole gate. Once installed, poco keeps itself current silently on the stable channel; early builds via poco update channel preview.

poco update channel preview # early builds

v0.3.0-preview.6 PREVIEW
  • TUI: zsh-style prefix history + inline ghost autosuggestions
  • vault: fetch the prod root token from GCS + KMS (ppterm parity)
  • Docs: v0.3.0-preview.5 released (run 265116 green, preview manifest + binary verified)

The installer always ships stable (v0.2.3). Opt in to early builds from inside poco — poco update channel preview — and back out anytime with poco update channel stable.

poco update # what's new in v0.2.3

v0.2.3 NEW
  • Release channels: opt in to preview builds with 'poco update channel preview'
  • Docs: landing page fully live — IAM granted, vanity URL TLS-verified
  • Landing page: poco.polypoint.dev — generated from tags + commander tree
  • CI: make the macOS smoke arch-adaptive — ADO hosted macs are Intel
  • CI matrix: build all 4 release targets on every main push + per-platform smoke

poco --help # 19 command groups

$ poco app

cloud pod operations against GKE deployments (kubectl wrappers with the Polypoint app registry baked in)

  • logs
  • exec
  • port-forward
  • port-forward-debug
  • restart
  • status
  • ping
  • health
  • scale

$ poco build

build cloud monorepo projects + docker images (mvnw + jib; renamed v1 build-zinc)

$ poco cmd

discovery: list and search every registered poco command

  • tree
  • search

$ poco completion

print a shell completion script (bash, zsh, fish) to stdout — or `install` it

  • install

$ poco config

inspect and edit `~/.poco/config.<profile>.yaml`

  • show
  • get
  • set
  • delete
  • edit
  • doctor
  • defaults

$ poco config-gen

surgical edits to the on-prem config-generator data in portal-core Postgres (templates, available keys, tenant configs)

  • templates
  • keys
  • tenant-configs
  • check
  • restore

$ poco db

port-forward an app's Postgres/MySQL (or the shared Redis) to localhost

  • port-forward
  • redis

$ poco dev

the inner loop: build → deploy → follow logs (cloud with -N, compose with --local); --watch redeploys on change

$ poco doctor

check local prerequisites for the Compose dev flow (--fix also repairs what it can)

$ poco local-build

deploy your local image build to a GKE namespace under a custom tag, and withdraw it again (M9)

  • deploy
  • withdraw

$ poco local-dev

drive the docker-compose local-dev stack (wraps the cloud/docker Makefile)

  • setup
  • up
  • down
  • reset
  • bootstrap
  • logs
  • ps
  • swap
  • unswap
  • swap-status
  • rebuild
  • rebuild-status
  • rebuild-reset
  • load-test-data
  • urls

$ poco mcp

serve poco as an MCP stdio server for agents (read-only tools; see `mcp tools`)

  • tools

$ poco onprem

on-prem (Nomad) operations: deploy/withdraw custom jars, restart, status, logs, port-forward

  • setup
  • deploy
  • withdraw
  • restart
  • system-status
  • logs
  • port-forward

$ poco ops

cluster-level operations (cleanup and maintenance against a whole GKE cluster)

  • clean-namespaces

$ poco setup

locate your cloud monorepo and save it to the active profile (first-run wizard)

$ poco snippet

manage `$name` snippets in the active profile config

  • list
  • set
  • show
  • rename
  • delete
  • promote
  • pull
  • retract

$ poco status

where am I pointed, what custom deploys are live, what runs locally, what jobs are open

$ poco update

check for a newer poco release and install it (see also: update channel | rollback)

  • channel
  • rollback

$ poco vault

HashiCorp Vault operations against the active GKE cluster (uses kubectl exec; no driver)

  • admin-token
  • sealed-status
  • unseal
  • port-forward
  • config
  • secrets

git log --tags # release stream

  1. v0.3.0-preview.6 PREVIEW NEW
    • TUI: zsh-style prefix history + inline ghost autosuggestions
    • vault: fetch the prod root token from GCS + KMS (ppterm parity)
    • Docs: v0.3.0-preview.5 released (run 265116 green, preview manifest + binary verified)
  2. v0.3.0-preview.5 PREVIEW
    • config-gen: generic data-surgery command set for the on-prem config generator (M20)
    • Docs: v0.3.0-preview.4 released (run 265079 green, preview manifest + binary verified)
  3. v0.3.0-preview.4 PREVIEW
    • Self-update: surface the restart hint in the session that downloaded it
    • Docs: v0.3.0-preview.3 released (run 20260612.1 green, preview manifest + binary verified)
  4. v0.3.0-preview.3 PREVIEW
    • TUI: jobs-panel focus + auto-clear, shell-like Ctrl+D, live parameter hint
    • dev: multi-service inner loop + nested-module watch fixes
    • Docs: v0.3.0-preview.2 released (run 20260611.8 green, preview manifest verified)
  5. v0.3.0-preview.2 PREVIEW
    • HomeBoard: don't gather (or hold the event loop) on a non-TTY
    • Docs: M19 wave 2 implemented — status notes per item, landing page skips hidden groups
    • M19 TUI home screen: live status board as the launch empty-state
    • M19 poco mcp: stdio MCP server over the read-only command surface
    • M19 hygiene: io.confirm() + destructive-op prompts, db redis fold, doctor --fix, onprem deploy progress + raw log
    • M19 dev --ephemeral: session port-forward + auto-withdraw on exit
    • M19 completion install: write the completion file + rc line idempotently
    • M19 update rollback: instant symlink swap to the previous version
    • M19 team awareness: generalize team-store, publish deploy records, status team section, deploy collision warning
    • Docs: M18 released (0.3.0-preview.1 + 0.2.3), record approved M19 wave-2 scope
  6. v0.3.0-preview.1 PREVIEW
    • Deflake the dev watcher test: assert the contract, not FSEvents timing
    • Register status/dev/completion in both entrypoints; update inside the TUI; M18 docs
    • Release channels: opt in to preview builds with 'poco update channel preview'
    • Shell completion for bash, zsh and fish
    • snippet promote/pull/retract: team-shared snippets in a private GCS bucket
    • poco dev: the inner loop as one command — build → deploy → logs
    • app health: the real deep health check, with a live --watch dashboard
    • poco status: the home screen — context, local stack, custom deploys, jobs
    • Self-healing port-forwards: auto-reconnect with backoff, auto-background as TUI jobs
  7. v0.2.3
    • Release channels: opt in to preview builds with 'poco update channel preview'
    • Docs: landing page fully live — IAM granted, vanity URL TLS-verified
    • Landing page: poco.polypoint.dev — generated from tags + commander tree
    • CI: make the macOS smoke arch-adaptive — ADO hosted macs are Intel
    • CI matrix: build all 4 release targets on every main push + per-platform smoke
  8. v0.2.2
    • Embed bundled resources in compiled binaries
    • Docs: record live distribution infra + vanity URL wiring
    • build-binaries: fix invalid manifest JSON + add parse gate
  9. v0.2.1
    • Track src/commands/build — was silently ignored by a global gitignore
  10. v0.2.0
    • Distribution: bun-compiled binary, gcloud-IAM gated installer, silent self-update
    • Prompt bar: word/line navigation, kill bindings, multi-line drafts
    • Unified default handling for namespace/db/onprem flags + live progress pipeline
    • db command group: port-forward to app DBs via cloud-sql-proxy sidecar
    • onprem command family + TUI virtualization for large output
    • Trim unused commands, compact vault output, add monorepo setup wizard
    • Background jobs: multitask port-forwards & long-running commands
    • TUI: scrollable transcript + stop tall output from crushing header/prompt
    • TUI: guided fill flow for templated snippets (Tab-cycle slots, Enter to advance)
    • TUI fullscreen by default + wire-up; app exec/logs/debug-port fixes; completion cycling
    • M9–M15: local-build, local-dev, istio, pubsub, 3rd-party, ops, auth, doctor
    • M4–M8: cmd, snippet, vault, k8s-secrets, config command groups
    • M3 polish: smarter tab completion, real GKE contexts, status/logs/Ctrl+C fixes
    • M3 follow-up: v1-parity app registry + debug-pod-mediated ping
    • M3 — app *: nine cloud pod-ops commands (CLI + TUI)
    • M2 — TUI shell: command runner, history, completion, processors, built-ins
    • M1 — Core platform: config, IO, shell, kube/gcloud, app registry, webex
    • Initial scaffold: Node + Ink + Commander CLI