--- name: pp-neon description: "Neon API commands in one static binary, plus a local fleet mirror for stale-branch cleanup, usage trends and compute audits. Trigger phrases: `find stale neon branches`, `clean up old neon branches`, `neon usage this week`, `create a neon preview branch`, `get a neon connection string`, `use neon`, `run neon`." author: "Greg Mushen" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - neon-pp-cli install: - kind: go bins: [neon-pp-cli] module: github.com/mvanhorn/printing-press-library/library/cloud/neon/cmd/neon-pp-cli --- # Neon — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `neon-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows: ```bash npx -y @mvanhorn/printing-press-library install neon --cli-only ``` 2. Verify: `neon-pp-cli --version` 3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill. If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.9 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead: ```bash go install github.com/mvanhorn/printing-press-library/library/cloud/neon/cmd/neon-pp-cli@latest ``` If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds. Manage Neon projects, branches, computes, roles and databases from the terminal with agent-native JSON and no Node runtime. Sync your account locally to get stale, tree, usage trend and compute audit, and use preview up and wait for per-PR branch workflows. ## When to Use This CLI Use this CLI to manage Neon control-plane resources: projects, branches, computes, roles, databases, operations and consumption. It suits per-PR branch automation, fleet audits and cost questions across many projects. ## Anti-triggers Do not use this CLI for: - Running SQL queries against a database; use psql with the connection string - Schema migrations; use your migration tool - Billing invoices and payment methods; use the Neon console ## Unique Capabilities ### Fleet hygiene - **`stale`** — Find idle or expired branches across every project from the local mirror (run sync first), with delete commands for non-default branches. _Reach for this before cleanup to see which preview branches are safe to remove._ ```bash neon-pp-cli stale --idle 14d --agent ``` - **`tree`** — See every org, project, branch and compute in one hierarchy from the local mirror (run sync first). _Use it to orient in an unfamiliar Neon account in one call._ ```bash neon-pp-cli tree --json ``` - **`prune`** — Preview idle or expired branches to delete (from the local mirror); --yes actually deletes them, always skipping default and protected branches. _Use after stale to actually clean up._ ```bash neon-pp-cli prune --idle 14d ``` ### Cost visibility - **`usage trend`** — Track compute, storage and transfer per project with period-over-period deltas; on plans without consumption history (below Launch/Scale) it uses per-sync snapshots (basis: sync-snapshots). _Use for questions about how usage changed over time._ ```bash neon-pp-cli usage trend --since 30d --agent ``` - **`usage top`** — Rank projects by compute, storage, transfer or written data; on plans without consumption history it ranks period-to-date totals from sync snapshots (basis: sync-snapshots). _Use to find which project drove a bill spike._ ```bash neon-pp-cli usage top --metric compute --since 7d --agent ``` - **`compute audit`** — Flag computes that never scale to zero, have fixed autoscaling, or are oversized on non-default branches, from the local mirror (run sync first). _Use to find the cheapest cost wins in a Neon fleet._ ```bash neon-pp-cli compute audit --agent ``` ### Preview branch workflow - **`wait`** — Block until a branch's async operations finish; exits 0 when done, 6 if an operation failed, 8 on timeout. _Use in CI or agent flows before connecting to a freshly created branch._ ```bash neon-pp-cli wait --branch pr-123 --project-id lucky-sun-123456 --timeout 5m ``` - **`preview up`** — Create a real branch (or reuse an existing one by name), wait until ready and print its connection string; --expires applies only to newly created branches. _Use for per-PR databases; safe to re-run._ ```bash neon-pp-cli preview up pr-123 --project-id lucky-sun-123456 --expires 7d --agent ``` ## Command Reference **connection-string** — Print a Postgres connection string for a branch, by name or ID. - `neon-pp-cli connection-string --project-id lucky-sun-123456 pr-123` — infers the database and owner role when the branch has one database; `--pooled`, `--database`, `--role`, `--format uri|env|psql`. **context** — Save a default project/org (like `neonctl set-context`). - `neon-pp-cli context set --project-id lucky-sun-123456` — then `connection-string`, `preview up` and `wait` work without `--project-id`. Also `context show` and `context clear`; `NEON_CONTEXT_FILE` selects a per-repo file. **Organization API keys** cannot call `/users/me`, `/regions` or `/api_keys` (Neon returns 404 "not allowed for organization API keys"); `users`, `regions` and `api-keys` commands need a personal API key. **api-keys** — These methods allow you to create and manage API keys for your Neon account. For related information, see [Manage API keys](https://neon.com/docs/manage/api-keys). - `neon-pp-cli api-keys create` — Creates an API key. The `key_name` is a user-specified name for the key. - `neon-pp-cli api-keys list` — Retrieves the API keys for your Neon account. The response does not include API key tokens. - `neon-pp-cli api-keys revoke` — Revokes the specified API key. An API key that is no longer needed can be revoked. This action cannot be reversed. **auth_details** — Manage auth details - `neon-pp-cli auth-details` — Returns authentication details for the credentials used in the request, including the credential type (API key **consumption-history** — Manage consumption history - `neon-pp-cli consumption-history get-per-branch-v2` — Returns consumption metrics for each branch across one or more projects listed in `project_ids` (1 to 100 projects). - `neon-pp-cli consumption-history get-per-project` — Retrieves consumption metrics for Scale, Business, and Enterprise plan projects. History begins at the time of upgrade. - `neon-pp-cli consumption-history get-per-project-v2` — Returns consumption metrics for up to `limit` projects per page. **organizations** — These methods allow you to manage your Neon organizations. - `neon-pp-cli organizations ` — Retrieves details for the specified organization, including its name, plan, and configuration. **projects** — These methods allow you to create and manage Neon projects. For related information, see [Manage projects](https://neon.com/docs/manage/projects). - `neon-pp-cli projects create` — Creates a Neon project within an organization. - `neon-pp-cli projects create-neon-auth-integration` — Deprecated. Use `/projects/{project_id}/branches/{branch_id}/auth` instead. Removal scheduled for March 1, 2026. - `neon-pp-cli projects create-neon-auth-new-user` — Deprecated. Use `/projects/{project_id}/branches/{branch_id}/auth/users` instead. Removal scheduled for March 1, 2026. - `neon-pp-cli projects create-neon-auth-provider-sdkkeys` — Generates SDK or API Keys for the auth provider. - `neon-pp-cli projects delete` — Deletes the specified project and all its endpoints, branches, databases, and users. - `neon-pp-cli projects get` — Retrieves information about the specified project. - `neon-pp-cli projects list` — Retrieves a list of projects for the specified organization. - `neon-pp-cli projects list-shared` — Retrieves a list of projects shared with your Neon account. For more information, see [Manage projects](https://neon. - `neon-pp-cli projects transfer-neon-auth-provider` — Transfers ownership of your Neon-managed auth project to your own auth provider account. - `neon-pp-cli projects update` — Updates the specified project. **regions** — These methods allow you to inspect Neon regions. - `neon-pp-cli regions` — Lists supported Neon regions. **Note:** Not all regions are available to all organizations. **users** — These methods allow you to manage your Neon user account. - `neon-pp-cli users get-current-info` — Retrieves information about the currently authenticated Neon user, including account identifiers, plan details - `neon-pp-cli users get-current-organizations` — Retrieves the organizations that the currently authenticated user belongs to. - `neon-pp-cli users transfer-projects-from-to-org` — Deprecated. Personal accounts have been migrated to organizations, so this operation no longer applies. **compute** - `neon-pp-cli compute audit` — Flag computes that never scale to zero, have fixed autoscaling, or are oversized on non-default branches, from the local mirror (run sync first). **preview** - `neon-pp-cli preview up` — Create a real branch (or reuse an existing one by name), wait until ready and print its connection string; --expires applies only to newly created branches. **prune** - `neon-pp-cli prune` — Preview idle or expired branches to delete (from the local mirror); --yes actually deletes them, always skipping default and protected branches. **stale** - `neon-pp-cli stale` — Find idle or expired branches across every project from the local mirror (run sync first), with delete commands for non-default branches. **tree** - `neon-pp-cli tree` — See every org, project, branch and compute in one hierarchy from the local mirror (run sync first). **usage** - `neon-pp-cli usage trend` — Track compute, storage and transfer per project with period-over-period deltas; on plans without consumption history (below Launch/Scale) it uses per-sync snapshots (basis: sync-snapshots). - `neon-pp-cli usage top` — Rank projects by compute, storage, transfer or written data; on plans without consumption history it ranks period-to-date totals from sync snapshots (basis: sync-snapshots). **wait** - `neon-pp-cli wait` — Block until a branch's async operations finish; exits 0 when done, 6 if an operation failed, 8 on timeout. ## Freshness Contract This printed CLI owns bounded freshness only for registered store-backed read command paths. In `--data-source auto` mode, those paths check `sync_state` and may run a bounded refresh before reading local data. `--data-source local` never refreshes. `--data-source live` reads the API and does not mutate the local store. Set `NEON_NO_AUTO_REFRESH=1` to skip the freshness hook without changing source selection. Covered paths: - `neon-pp-cli projects list` - `neon-pp-cli projects get` - `neon-pp-cli stale`, `neon-pp-cli tree`, `neon-pp-cli compute audit`, `neon-pp-cli usage top`, `neon-pp-cli usage trend` and `neon-pp-cli prune` read the local mirror only; run `neon-pp-cli sync` first. When JSON output uses the generated provenance envelope, freshness metadata appears at `meta.freshness`. Treat it as current-cache freshness for the covered command path, not a guarantee of complete historical backfill or API-specific enrichment. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash neon-pp-cli which "" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. `--json` (and other machine formats) keep that exit-2 contract and write `{"matches":[]}` on stdout so agents can inspect the envelope without treating a miss as success. ## Recipes ### Per-PR database ```bash neon-pp-cli preview up pr-123 --project-id lucky-sun-123456 --expires 7d --agent ``` Creates or reuses the branch and prints its connection string. ### Cleanup preview ```bash neon-pp-cli stale --idle 14d --agent --select branch_name,project_id,last_active_at ``` Narrow output to the fields you need for a cleanup decision. ### Bill spike ```bash neon-pp-cli usage top --metric compute --since 7d ``` Rank projects by compute over the last week. ### Clean up idle branches ```bash neon-pp-cli prune --idle 14d ``` Previews what would be deleted; re-run with --yes to delete (default and protected branches are always skipped). ### Save a default project ```bash neon-pp-cli context set --project-id lucky-sun-123456 ``` connection-string, preview up and wait then work without --project-id. ## Auth Setup Run `neon-pp-cli auth setup` for the URL and steps to obtain a token (add `--launch` to open the URL). Then store it: ```bash echo "$TOKEN" | neon-pp-cli auth set-token ``` Or set `NEON_API_KEY` as an environment variable. Run `neon-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color`. Global format flags share one contract on promoted, novel, sync, and `--deliver` paths: - `--json` — one JSON document on stdout (sync progress events go to stderr) - `--compact` — keep identity/status/timestamp fields; does not change the document vs stream shape - `--csv` / `--plain` — tabular rows (collection envelopes unwrap to the row array) - `--quiet` — one identity value per row, no envelope - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash neon-pp-cli projects list --agent --select projects.id,projects.name,projects.region_id ``` - **Previewable** — `--dry-run` shows the request without sending - **Offline-friendly** — sync/search commands can use the local SQLite store when available - **Non-interactive** — never prompts, every input is a flag - **Explicit confirmation** — `--agent` does not imply `--yes`; pass `--yes` separately only after the target, arguments, and side effects are clear - **Explicit retries** — use `--idempotent` only when an already-existing create should count as success, and use `--ignore-missing` only when a missing delete target should count as success ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout. ## Paths and state Agents should treat the CLI's path resolver as part of the runtime contract: - Use `--home ` for one invocation, or set `NEON_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `NEON_CONFIG_DIR`, `NEON_DATA_DIR`, `NEON_STATE_DIR`, `NEON_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `NEON_HOME`, XDG (`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`), then platform defaults. - `config` contains settings like `config.toml` and profiles. `data` contains `credentials.toml`, `data.db`, and auth sidecars. `state` contains persisted queries, jobs, and `teach.log`. `cache` contains regenerable HTTP/cache files. - Stored secrets live in `credentials.toml` under the data dir. Existing legacy `config.toml` secrets are read for compatibility and leave `config.toml` on the first auth write. - Run `neon-pp-cli doctor --fail-on warn` to surface path and credential-location warnings. `agent-context` exposes a schema v4 `paths` block for agents that need the resolved dirs. - For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags: ```json { "mcpServers": { "neon": { "command": "neon-pp-mcp", "env": { "NEON_HOME": "/srv/neon" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `NEON_HOME` or per-kind vars as durable fleet levers, and use `--home` only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing `NEON_HOME`, or `doctor` will not find credentials left under the former root. ## Automatic learning This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a `flag_alias` candidate, and a `teach` on a query family without a playbook auto-synthesizes a `playbook_candidate` from the session's journal. Your job is judgment only: `recall` first, act on surfaced candidates, `teach` the final answer, `playbook amend` when you observe a correction. You never record failures by hand. ### Step 1: `recall` before any discovery Before list/search/drill commands on a new user question, pass the question as an argv or MCP tool argument to `recall --agent`. Do not interpolate user-controlled text into a shell command line. Quoted `recall ""` breaks on an apostrophe, which is ordinary English. A quoted heredoc breaks when a body line equals the delimiter, and that delimiter is published in these docs. Write the question with a non-shell file-writing tool, then read it back as data: ```bash # Write the question verbatim with your file-writing tool (no shell involved). # Command substitution on a file only ever yields data — the shell never # parses the file's bytes as syntax. QUERY=$(cat /path/to/question.txt) neon-pp-cli recall "$QUERY" --agent ``` Prefer MCP: pass the question as the tool's query argument. `"$QUERY"` after a file read is argv-safe; putting the question itself in the command text is not. The response envelope: ```json { "query": "...", "normalized": "", "query_entities": ["..."], "found": true | false, "match_score": 0.0, "results": [ { "resource_id": "...", "resource_type": "...", "venue": "...", "confidence": 2, "entity_match": "exact|partial|unknown", "source": "taught|preseed|pattern", "warnings": ["..."] } ], "mismatches": [ /* only when --debug-mismatches */ ], "warnings": [ /* top-level */ ], "candidates": [ { "id": 12, "class": "flag_alias | playbook_candidate", "summary": "...", "sightings": 3, "last_seen": "...", "rationale": "...", "next_action": ["", "neon-pp-cli learnings confirm 12"] } ], "playbook": { "query_family": "...", "playbook": { "steps": [ { "cmd": "", "purpose": "..." } ], "entity_slots": ["$ENTITY"], "expected_tool_calls": 3 },