>poco

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

v0.3.3 preview v0.5.0-preview.5
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 # two release tracks

stable v0.3.3

Ships with the installer and updates itself silently — nothing to do.

$ curl -fsSL https://get-poco.polypoint.dev | bash

The default channel. Already installed? You’re already on it.

  • `poco --version` (and `-V`) now works inside the interactive TUI, not just the one-shot CLI.
  • Clearer update errors: a 403 from the release bucket now points you at `gcloud auth login` (you're signed in with the wrong Google account) instead of a raw HTTP code; a 404 says the channel simply has no release published yet.
  • A channel switch (`poco update channel stable`) no longer strands you on a raw error if the immediate check can't reach the manifest.
preview v0.5.0-preview.5

Early builds of what’s next. Opt in from inside poco; switch back anytime.

$ poco update channel preview

Already on stable? Run this in poco. Back out with poco update channel stable.

  • Forgotten custom deploys now escalate instead of fading: a held deploy's age on the home board and in `status` stays dim for 3 days, turns yellow after that, and goes red with a ⚠ after a week — across your own GKE tags, on-prem jars, and teammates' rows alike. Stale rows on the board also grow a hint naming both ways out, so a 24-day-old custom jar can no longer hide as the quietest line on screen.
  • `onprem withdraw --forget` drops the saved deployment record without touching the target — for deploys the target already reconciled out-of-band (redeployed since, rolled back by hand), where a real withdraw would stop the job and restore a weeks-old backup over its current state. It matches records directly (module or spring.application.name) with no inventory resolution and no SSH session, so it works even when the target has since left the inventory. Parity with `local-build withdraw --forget`; the withdraw hints in `status` now mention it.

poco --help # 23 command groups

$ poco activity

team activity timeline — see and undo every mutating action (--undo <id>)

$ 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.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 map

live service map of a namespace — health, deploy tags, forwards (interactive as /map in the TUI)

$ 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 playbook

living team runbooks — multi-step, shareable, with confirm/pause/onFail directives

  • list
  • show
  • run
  • edit
  • promote
  • pull
  • retract
  • delete

$ poco setup

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

$ poco snippet

manage `$name` snippets in the 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

$ poco watch

read-only dashboard — multi-app health, local stack, team deploys, activity (the static render of /dashboard; interactive & live in the TUI)

git log --tags # release stream · two tracks

stable

  1. v0.3.3 NEW
    • `poco --version` (and `-V`) now works inside the interactive TUI, not just the one-shot CLI.
    • Clearer update errors: a 403 from the release bucket now points you at `gcloud auth login` (you're signed in with the wrong Google account) instead of a raw HTTP code; a 404 says the channel simply has no release published yet.
    • A channel switch (`poco update channel stable`) no longer strands you on a raw error if the immediate check can't reach the manifest.
  2. v0.3.2
    • # v0.3.2
    • ## /snapshot — debug snapshots for Claude Code
    • Whenever something fails — a build, a docker push, a port-forward, a random
    • command — run `/snapshot` to copy a structured debug prompt to your clipboard.
    • Paste it into Claude Code at the root of the repo and it has everything needed
    • to diagnose and fix the issue:
    • **Full session transcript** with every command, its status (✓/✗/●), duration,
    • and complete output (stdout/stderr/debug color-coded with `[stderr]` prefixes)
    • **Environment metadata** — poco version, platform, node version, kube context,
    • cloud monorepo path, working directory
    • **Smart failure detection** — auto-counts failures, highlights the most recent
    • one, and the generated prompt tells Claude Code how to fix it (environmental
    • issue → fix locally, poco bug → PR, cloud repo bug → PR)
    • When a command fails, the hint row automatically suggests running `/snapshot`.
    • ## Shell escape (`!` prefix)
    • Claude Code-style bang prefix: type `! <cmd>` to run the rest of the line in
    • your host shell. Native operators (pipes, `&&`, redirects, globbing, `$VAR`
    • expansion) all work. The prompt bar switches to a bold green `$` style to make
    • shell mode visually unmistakable.
    • ## Completion menu revamp
    • Tab completion candidates are now a vertically stacked menu with inline
    • descriptions and active-candidate highlighting — like Claude Code's completion
    • popup. Commands and options show their help text inline, and new commands get a
    • dynamic `new` badge that auto-clears after the user's version catches up.
    • ## Tip banners
    • A rotating one-liner surfaces features the user might not know about (new
    • features first, then evergreen tips), shown above the home board. Disable via
    • `tui.tips.enabled: false`.
    • --
    • 34 new tests for the completion menu / tips, 20 new tests for the snapshot
    • module (954 total).
  3. v0.3.1
    • TUI: vertical completion menu with descriptions, NEW badges, and tip banners
    • Fix: use readFileSync instead of fs.readFileSync in build-site.ts
    • Release: v0.3.0 stable — curated release notes + landing page support
  4. v0.3.0
    • The full pocofication: everything from raw command groups to a live, team-aware TUI.
    • Interactive home board, inner dev loop, ghost autosuggestions, self-healing port-forwards,
    • team deploy awareness, MCP server, and the config-gen data surgery suite.
    • Self-update now surfaces the restart hint in the session that downloaded it.
    • Removed the profile system (single-config simplicity); added /context switching with Tab completion.
    • gcloud credential caching wired into every deploy path (was dead code before).
  5. 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
  6. 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
  7. v0.2.1
    • Track src/commands/build — was silently ignored by a global gitignore
  8. 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

preview

  1. v0.5.0-preview.5 NEW
    • Forgotten custom deploys now escalate instead of fading: a held deploy's age on the home board and in `status` stays dim for 3 days, turns yellow after that, and goes red with a ⚠ after a week — across your own GKE tags, on-prem jars, and teammates' rows alike. Stale rows on the board also grow a hint naming both ways out, so a 24-day-old custom jar can no longer hide as the quietest line on screen.
    • `onprem withdraw --forget` drops the saved deployment record without touching the target — for deploys the target already reconciled out-of-band (redeployed since, rolled back by hand), where a real withdraw would stop the job and restore a weeks-old backup over its current state. It matches records directly (module or spring.application.name) with no inventory resolution and no SSH session, so it works even when the target has since left the inventory. Parity with `local-build withdraw --forget`; the withdraw hints in `status` now mention it.
  2. v0.5.0-preview.4
    • `poco dev --watch` now rolls a fresh pod on every save: re-deploying the same custom tag used to patch the deployment to an identical spec — a no-op that left the old pod running stale code — so a same-tag deploy now follows the patch with a rollout-restart, and the just-pushed image is actually pulled and served (the deploy line reads `… · rolling restart (same tag)`). This also fixes a plain `local-build deploy` re-run with an unchanged tag.
    • Smarter watch debounce: source changes settle over a 2s window (was 1s) with a max-wait ceiling, so a burst of edits — e.g. an AI agent rewriting many files back-to-back — coalesces into one rebuild instead of a storm of redeploys, while a continuously-edited tree still rebuilds instead of starving. Tune the settle window with `poco dev --watch --debounce <seconds>`.
  3. v0.5.0-preview.3
    • Safer, consistent map keys: in `/map`, `r` now refreshes (it used to rollout-restart — a genuine footgun), `R` rollout-restarts, `p` toggles live polling, `h` runs the deep health check, and `q` closes any open panel everywhere. Selection stays identity-based so the cursor never jumps when the grid re-sorts.
    • The dashboard shows real port-forwards: the health pane is wired to your live forwards (it was previously inert), and `poco watch` drops its dead forward column and refreshes on the same shared formatters as `/dashboard` — one consistent picture of health, activity and forwards everywhere.
    • Rollout status reads honestly: a deploy that's progressing now says "running", with "healthy" reserved for the deep `app health` probe — so the board never overstates a service.
    • New `local-build withdraw --forget`: drop poco's record of a custom deploy WITHOUT rolling the cluster back — for deploys you already reconciled out-of-band (a manual ArgoCD re-sync or hand kubectl), so the status board stops listing custom deploys that are already gone.
    • Under the hood: the presentation layer is consolidated behind shared formatters and a single command registry, duplicate panes folded into their one home, and the "what's new" badges now advance correctly between versions — a smaller, fully-tested codebase with no behaviour you relied on removed.
  4. v0.5.0-preview.2
    • Mission control dashboard: poco stops being the thing you invoke and becomes the screen you keep up all day. Type `/dashboard` in the TUI for an always-on split view — health tiles, the team activity timeline, the local compose stack, active port-forwards, a log tail, and who-holds-what — pinned above a still-live prompt, so you watch while you work. `Ctrl+O` focuses the panes; Tab cycles, `r` refreshes, `e` expands one to fill the screen, and `a` opens arrange mode to add / move / remove panes (saved per-profile). `poco watch [namespace]` prints the same picture from the CLI, read-only and refreshing in place (or `--once` for a single render).
    • Navigable live service map — poco's embedded k9s. Type `/map` (or `/map prod`) in the TUI for a full-screen, navigable picture of a namespace: every Polypoint app as a cell with a live health glyph (● running · ◑ degraded · ○ down · ⚠ unknown), its custom deploy tag (yours or a teammate's), and any active port-forward. `poco map [namespace]` prints the same picture as a static render from the CLI.
    • Drive it with the keyboard: ↑↓←→ / j k to move, `/` to fuzzy-filter, `[` `]` (or Tab) to switch namespace, `R` to toggle live refresh, and Enter to drill into an app's pods (ready / status / restarts / age / node).
    • Act in place with full k9s-grade power: `l` streams logs (follow + scroll), `d` describes, `y` shows raw YAML, `s` opens a shell in the pod, `f` port-forwards, `h` runs the deep health check. Mutations — `r` rollout-restart, `S` scale, `x` delete pod, `c` cordon node — route through poco's real pipeline, so every one produces a card, is recorded to the team activity ledger, and is undoable. On the PROD cluster, destructive actions require typing the resource name to confirm.
    • Selection is identity-based, so the cursor never jumps to the wrong app when the grid re-sorts on a refresh.
  5. v0.5.0-preview.1
    • Universal undo + team activity timeline: every mutating command is now reversible and recorded to a shared team ledger. See who did what with `poco activity` (or `/activity`, Ctrl+T for the panel), and revert any entry with `poco activity --undo <id>`.
    • Every mutating command prints a one-line `↩ undo with: …` hint on success, so nothing poco does is ever a dead end.
    • Living team runbooks (playbooks): chain commands into reusable, multi-step runbooks with confirm / pause / onFail steps. `playbook edit <name>` to author, `playbook run <name>` to execute, plus `list` / `show` / `promote` / `pull` / `retract`. Works from the CLI or `/playbook` in the TUI.
    • Inherits the v0.3.3 fixes: TUI `poco --version`, and clearer `update` errors (403 → check your gcloud account, 404 → nothing published yet).
  6. v0.4.0-preview.1
    • Re-sync: the preview channel is back in line with the latest stable (v0.3.2) — no more falling behind.
    • /snapshot copies a structured debug prompt to your clipboard for Claude Code (full transcript, env metadata, smart failure detection).
    • Shell escape (!) prefix to run the rest of the line in your host shell; prompt bar switches to a bold green $ style.
    • Completion menu revamp — vertical menu with inline descriptions, active-candidate highlight, and dynamic `new` badges.
    • Rotating tip banners above the home board surface features you might not know about (disable with tui.tips.enabled: false).
  7. v0.3.0-preview.8
    • Remove profile system (single-config simplicity); add /context slash command with Tab completion;
    • wire gcloud credential caching into every deploy path (was dead code before);
    • fix update-notice hint to surface immediately after download instead of 60s later.
  8. v0.3.0-preview.7
    • Fix update-notice hint: surface immediately after check, not 60s later
    • Remove profile system; wire gcloud auth caching + /context switching
    • Docs: v0.3.0-preview.6 released (run 265132 green, preview manifest + binary verified)
  9. v0.3.0-preview.6
    • 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)
  10. v0.3.0-preview.5
    • 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)
  11. v0.3.0-preview.4
    • 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)
  12. v0.3.0-preview.3
    • 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)
  13. v0.3.0-preview.2
    • 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
  14. v0.3.0-preview.1