From a47821854ec9ec03bc7d7ab9c99caa5d0a592ac6 Mon Sep 17 00:00:00 2001 From: Carlota Soto Date: Tue, 25 Aug 2026 09:16:59 -0700 Subject: [PATCH 1/4] Add blog post on what's new in the Neon CLI --- .../blog/posts/just-landed-in-the-neon-cli.md | 253 ++++++++++++++++++ 1 file changed, 253 insertions(+) create mode 100644 content/blog/posts/just-landed-in-the-neon-cli.md diff --git a/content/blog/posts/just-landed-in-the-neon-cli.md b/content/blog/posts/just-landed-in-the-neon-cli.md new file mode 100644 index 0000000000..fc413ac4a0 --- /dev/null +++ b/content/blog/posts/just-landed-in-the-neon-cli.md @@ -0,0 +1,253 @@ +--- +title: Just landed in the Neon CLI +description: >- + New commands for branch-first workflows, Postgres diagnostics, schema diffs, + and a lot more +excerpt: >- + The Neon CLI moved fast over the last couple of months. It is a key tool for + agents, who do all the work without ever opening the Console - let’s take a + look at some of recent changes. +date: '2026-08-25T12:00:00' +updatedOn: '2026-08-25T15:57:00' +category: product +categories: + - product +authors: + - carlota-soto +cover: + image: null + alt: null +isFeatured: false +seo: + title: Just landed in the Neon CLI - Neon + description: >- + New commands for branch-first workflows, Postgres diagnostics, schema diffs, + and a lot more + keywords: [] + noindex: false + ogTitle: Just landed in the Neon CLI - Neon + ogDescription: >- + New commands for branch-first workflows, Postgres diagnostics, schema diffs, + and a lot more + image: null +--- + +The [Neon CLI](https://neon.com/docs/cli) moved fast over the last couple of months. It is a key tool for agents, who do all the work without ever opening the Console - let’s take a look at some of recent changes: + +## The CLI is now neon + +First things first, the npm package and docs use neon instead of neonctl. Same binary, shorter name. + +So, to [install it](https://neon.com/docs/cli/install), + +``` +npm i -g neon@latest +neon auth +``` + +For agents, set up skills and the MCP server in one shot: + +``` +npx neon@latest init +``` + +neonctl still works as an alias - no re-auth is required if you already used the old name. + +## New commands for branch-first workflows: link, checkout, env pull + +These three commands are the [core loop for local (and agent) development](https://neon.com/blog/branch-first-dev-loop): + +``` +neon link # bind this directory to a Neon project (.neon context) +neon checkout my-feature # create or pin a branch; env pull runs by default +neon env pull # refresh Neon-managed vars into .env / .env.local +``` + +[neon link](https://neon.com/docs/cli/link) writes a local .neon context (orgId, projectId, branchId). You can use --agent for non-interactive JSON mode. Once linked, you can drop --project-id / --branch on most commands. The CLI walks up parent folders to find .neon, and adds it to .gitignore on first write. + +[neon checkout](https://neon.com/docs/cli/checkout) pins the active branch in that context, the same way you'd switch a git branch. + +[neon env pull](https://neon.com/docs/cli/env) writes branch-scoped Neon variables (DATABASE_URL, unpooled URL, and credentials for enabled services). Only Neon-managed keys are rewritten; the rest of your [env](https://neon.com/docs/cli/env) file is left alone. + +A recent refinement - pull only the services you name (postgres, auth, data-api, object-storage, or ai-gateway): + +``` +neon env pull --service ai-gateway --service postgres +``` + +## Jump to the Console: neon open + +A cool trick: run + +``` +neon open +``` + +To [open](https://neon.com/docs/cli/open) the linked project's dashboard in your browser. + +## See the pinned branch: neon status + +This command [prints the branch](https://neon.com/docs/cli/config#current-branch) in .neon with no network call, so it's safe for shell prompts: + +``` +neon status +``` + +## Credentials: api-keys and profile + +We shipped these two command groups together, useful for CI and multi-account work: + +### Mint scoped keys with neon api-keys + +``` +neon api-keys create --name ci # account key +neon api-keys create --name ci --org-id org-example-12345678 # organization key +neon api-keys create --name agent --project-id green-breeze-12345678 # one project only +``` + +A [project-scoped key](https://neon.com/docs/cli/api-keys) cannot create projects, mint more keys, or see other projects (i.e. what you’d want for an agent or a CI job). + +### Switch accounts with neon profile + +A profile is a named credentials set. Select it per command with [--profile](https://neon.com/docs/cli/profile): + +``` +neon auth --profile work +neon deploy --profile work +neon profile create ci --mint --project-id green-breeze-12345678 +``` + +--mint signs in once, stores only the minted key, and leaves no browser session behind. + +## Print schema diffs with neon diff + +[neon diff](https://neon.com/docs/cli/diff) prints a git-style unified schema diff between the branch under review and a compare branch (by default, the reviewed branch's parent) + +- For a machine-readable output, run --output json or --output yaml +- For a historical point in time (timestamp or LSN), use neon branches schema-diff instead + +``` +neon link +neon checkout feature/checkout +# ... change schema ... +neon diff main +``` + +## Call any Neon API route with neon api + +When you need a route that does not have a CLI command yet, use the [authenticated passthrough](https://neon.com/docs/cli/api) - this command uses your existing CLI login: + +``` +neon api --list +neon api /projects -Q org_id=org-cool-darkness-12345678 +neon api /projects/late-frost-12345678/branches -X POST -F branch.name=dev +``` + +-F branch.name=dev builds nested JSON. Bodies can also come from -d @file. + +## Debug Postgres via neon inspect db + +This [diagnostics tool](https://neon.com/docs/cli/inspect) bundles 14 read-only diagnostics against Postgres stats and catalogs, with connection resolution handled by the CLI: + +``` +neon link +neon inspect db bloat +neon inspect db outliers +neon inspect db unused-indexes +``` + +Examples of what you get: + +- table/index sizes +- bloat estimates +- unused indexes +- sequential scans +- long-running queries +- Locks +- pg_stat_statements outliers/calls +- vacuum stats +- replication slots/subscriptions +- and Neon Local File Cache hit rate / working set ([inspect](https://neon.com/docs/cli/inspect), [deep dive](https://neon.com/blog/neon-inspect-db), [changelog](https://neon.com/docs/changelog/2026-07-24#debug-postgres-from-the-terminal-with-neon-inspect-db)). + +It works against a linked branch, or any Postgres URL via --db-url. Same checks are also available on the Neon MCP server as inspect_database. + +## Snapshots from the terminal: neon snapshots + +[Point-in-time branch backups](https://neon.com/docs/cli/snapshots) are now first-class in the CLI: + +``` +neon snapshots create --branch main --name pre-migration +neon snapshots list +neon snapshots restore pre-migration --name recovered +``` + +You can restore un-finalized (inspect first), then neon snapshots finalize, or pass --finalize to swap immediately. For schedules: neon snapshots schedule get / set. + +## What’s new in Auth, Data API, and psql + +### Enable Managed Better Auth via neon neon-auth + +You can now directly enable Auth, configure OAuth providers and domains, tweak email/webhook settings, and manage users [from the terminal](https://neon.com/docs/cli/neon-auth): + +``` +neon neon-auth enable +neon neon-auth oauth-provider add --provider-id google +neon neon-auth domain add https://myapp.com +``` + +### Manage the Data API via neon data-api + +You can also [provision and manage](https://neon.com/docs/cli/data-api) the Data API (create, get, update, refresh-schema, delete). + +### neon psql without a local psql install + +[neon psql](https://neon.com/docs/cli/psql) connects as a top-level command. If no native psql is on $PATH, the CLI falls back to a built-in client. + +## Project create flags and declarative config + +[neon projects create](https://neon.com/docs/cli/projects) now accepts more up-front control - e.g. you can specify Postgres version, protected branches, logical replication: + +``` +neon projects create --name my-app --pg-version 17 +``` + +For declarative branch policy, neon config init scaffolds a starter [neon.ts](https://neon.com/docs/reference/neon-ts) and installs @neon/config / @neon/env. neon link can offer this as a final step. + +[Backend service commands](https://neon.com/docs/cli) such as neon functions and neon buckets are part of the same CLI surface as Object Storage, Functions, and AI Gateway roll out. + +## The latest commands at a glance + +| Goal | Command | Docs | +| --- | --- | --- | +| Install / upgrade | `npm i -g neon@latest` | [install](https://neon.com/docs/cli/install) | +| Sign in | `neon auth` | [auth](https://neon.com/docs/cli/auth) | +| Link a project | `neon link` | [link](https://neon.com/docs/cli/link) | +| Switch branch + env | `neon checkout ` | [checkout](https://neon.com/docs/cli/checkout) | +| Pull env (optionally by service) | `neon env pull [--service …]` | [env](https://neon.com/docs/cli/env) | +| Open Console | `neon open` | [open](https://neon.com/docs/cli/open) | +| Mint / revoke API keys | `neon api-keys …` | [api-keys](https://neon.com/docs/cli/api-keys) | +| Multi-account credentials | `neon profile …` | [profile](https://neon.com/docs/cli/profile) | +| Schema diff | `neon diff [branch]` | [diff](https://neon.com/docs/cli/diff) | +| Any API route | `neon api ` | [api](https://neon.com/docs/cli/api) | +| Postgres diagnostics | `neon inspect db ` | [inspect](https://neon.com/docs/cli/inspect) | +| Snapshots | `neon snapshots …` | [snapshots](https://neon.com/docs/cli/snapshots) | +| Auth management | `neon neon-auth …` | [neon-auth](https://neon.com/docs/cli/neon-auth) | +| Data API | `neon data-api …` | [data-api](https://neon.com/docs/cli/data-api) | +| SQL shell | `neon psql` | [psql](https://neon.com/docs/cli/psql) | +| Agent / MCP setup | `npx neon@latest init` | [init](https://neon.com/docs/cli/init) | + +## What to put in AGENTS.md + +If you want coding agents to use the branch-first loop by default, a short rule is enough: + +When starting a feature, run `neon checkout ` alongside `git checkout -b`. + +Prefer project-scoped API keys (`neon api-keys create --project-id …`) for automation. + +Use `neon diff` before merging schema changes, and `neon inspect db` for read-only Postgres diagnostics. + +Install current Neon skills so the agent knows the new commands: + +``` +npx neon@latest init +``` From bf87a94349c801a4f93ca2207e07d2834d6e08e5 Mon Sep 17 00:00:00 2001 From: Ilya Topilskii Date: Tue, 25 Aug 2026 21:52:04 +0200 Subject: [PATCH 2/4] Add cover image to Neon CLI blog post (#5634) --- content/blog/posts/just-landed-in-the-neon-cli.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/blog/posts/just-landed-in-the-neon-cli.md b/content/blog/posts/just-landed-in-the-neon-cli.md index fc413ac4a0..a7455c0c2c 100644 --- a/content/blog/posts/just-landed-in-the-neon-cli.md +++ b/content/blog/posts/just-landed-in-the-neon-cli.md @@ -15,7 +15,8 @@ categories: authors: - carlota-soto cover: - image: null + image: >- + https://cdn.neonapi.io/public/images/pages/blog/just-landed-in-the-neon-cli/neon-just-landed.jpg alt: null isFeatured: false seo: From e04c5db7d785b93d3d3953a7adab9443a7cc1924 Mon Sep 17 00:00:00 2001 From: Carlota Soto Date: Tue, 25 Aug 2026 13:31:53 -0700 Subject: [PATCH 3/4] blog: apply review feedback to Neon CLI roundup post Add cover image to the post body and SEO metadata, move inspect db up as a major highlight, reframe neon api as an agent fallback, document neon mcp and neon skills, and turn the AGENTS.md section into a copy-paste block. --- .../blog/posts/just-landed-in-the-neon-cli.md | 89 +++++++++++-------- 1 file changed, 52 insertions(+), 37 deletions(-) diff --git a/content/blog/posts/just-landed-in-the-neon-cli.md b/content/blog/posts/just-landed-in-the-neon-cli.md index a7455c0c2c..5a219dcc5b 100644 --- a/content/blog/posts/just-landed-in-the-neon-cli.md +++ b/content/blog/posts/just-landed-in-the-neon-cli.md @@ -17,7 +17,7 @@ authors: cover: image: >- https://cdn.neonapi.io/public/images/pages/blog/just-landed-in-the-neon-cli/neon-just-landed.jpg - alt: null + alt: Just landed in the Neon CLI isFeatured: false seo: title: Just landed in the Neon CLI - Neon @@ -30,9 +30,12 @@ seo: ogDescription: >- New commands for branch-first workflows, Postgres diagnostics, schema diffs, and a lot more - image: null + image: >- + https://cdn.neonapi.io/public/images/pages/blog/just-landed-in-the-neon-cli/neon-just-landed.jpg --- +![Just landed in the Neon CLI](https://cdn.neonapi.io/public/images/pages/blog/just-landed-in-the-neon-cli/neon-just-landed.jpg) + The [Neon CLI](https://neon.com/docs/cli) moved fast over the last couple of months. It is a key tool for agents, who do all the work without ever opening the Console - let’s take a look at some of recent changes: ## The CLI is now neon @@ -49,11 +52,21 @@ neon auth For agents, set up skills and the MCP server in one shot: ``` -npx neon@latest init +neon init ``` neonctl still works as an alias - no re-auth is required if you already used the old name. +## Agent tooling: neon init, mcp, and skills + +If you're wiring up a coding agent, you have three focused entry points: + +- [`neon init`](https://neon.com/docs/cli/init) - full onboarding: OAuth, API key, MCP server, editor extension, and agent skills +- [`neon mcp`](https://neon.com/docs/cli/mcp) - MCP server only +- [`neon skills`](https://neon.com/docs/cli/skills) - agent skills only + +`neon init` is the one-shot setup. Use `mcp` or `skills` when you only need one piece. To refresh skills you've already installed, run `neon skills update`. + ## New commands for branch-first workflows: link, checkout, env pull These three commands are the [core loop for local (and agent) development](https://neon.com/blog/branch-first-dev-loop): @@ -76,6 +89,32 @@ A recent refinement - pull only the services you name (postgres, auth, data-api, neon env pull --service ai-gateway --service postgres ``` +## Debug Postgres via neon inspect db + +This [diagnostics tool](https://neon.com/docs/cli/inspect) bundles read-only diagnostics against Postgres stats and catalogs, with connection resolution handled by the CLI: + +``` +neon link +neon inspect db bloat +neon inspect db outliers +neon inspect db unused-indexes +``` + +Examples of what you get: + +- table/index sizes +- bloat estimates +- unused indexes +- sequential scans +- long-running and stalled queries +- locks +- pg_stat_statements outliers/calls +- vacuum stats +- replication slots/subscriptions +- and Neon Local File Cache hit rate / working set ([inspect](https://neon.com/docs/cli/inspect), [deep dive](https://neon.com/blog/neon-inspect-db), [changelog](https://neon.com/docs/changelog/2026-07-24#debug-postgres-from-the-terminal-with-neon-inspect-db)). + +Omit the database name to inspect every database on the branch (the output adds a `database` column). It works against a linked branch, or any Postgres URL via --db-url. Same checks are also available on the Neon MCP server as `inspect_database`. + ## Jump to the Console: neon open A cool trick: run @@ -134,9 +173,9 @@ neon checkout feature/checkout neon diff main ``` -## Call any Neon API route with neon api +## Call any Neon API route with neon api (agent fallback) -When you need a route that does not have a CLI command yet, use the [authenticated passthrough](https://neon.com/docs/cli/api) - this command uses your existing CLI login: +Most humans will never need this. Coding agents reach for [`neon api`](https://neon.com/docs/cli/api) when they need an API route that doesn't have a dedicated CLI command yet - a fallback for automation, not day-to-day terminal work. It uses your existing CLI login: ``` neon api --list @@ -146,32 +185,6 @@ neon api /projects/late-frost-12345678/branches -X POST -F branch.name=dev -F branch.name=dev builds nested JSON. Bodies can also come from -d @file. -## Debug Postgres via neon inspect db - -This [diagnostics tool](https://neon.com/docs/cli/inspect) bundles 14 read-only diagnostics against Postgres stats and catalogs, with connection resolution handled by the CLI: - -``` -neon link -neon inspect db bloat -neon inspect db outliers -neon inspect db unused-indexes -``` - -Examples of what you get: - -- table/index sizes -- bloat estimates -- unused indexes -- sequential scans -- long-running queries -- Locks -- pg_stat_statements outliers/calls -- vacuum stats -- replication slots/subscriptions -- and Neon Local File Cache hit rate / working set ([inspect](https://neon.com/docs/cli/inspect), [deep dive](https://neon.com/blog/neon-inspect-db), [changelog](https://neon.com/docs/changelog/2026-07-24#debug-postgres-from-the-terminal-with-neon-inspect-db)). - -It works against a linked branch, or any Postgres URL via --db-url. Same checks are also available on the Neon MCP server as inspect_database. - ## Snapshots from the terminal: neon snapshots [Point-in-time branch backups](https://neon.com/docs/cli/snapshots) are now first-class in the CLI: @@ -222,6 +235,9 @@ For declarative branch policy, neon config init scaffolds a starter [neon.ts](ht | --- | --- | --- | | Install / upgrade | `npm i -g neon@latest` | [install](https://neon.com/docs/cli/install) | | Sign in | `neon auth` | [auth](https://neon.com/docs/cli/auth) | +| Agent onboarding | `neon init` | [init](https://neon.com/docs/cli/init) | +| MCP server only | `neon mcp` | [mcp](https://neon.com/docs/cli/mcp) | +| Agent skills only | `neon skills` | [skills](https://neon.com/docs/cli/skills) | | Link a project | `neon link` | [link](https://neon.com/docs/cli/link) | | Switch branch + env | `neon checkout ` | [checkout](https://neon.com/docs/cli/checkout) | | Pull env (optionally by service) | `neon env pull [--service …]` | [env](https://neon.com/docs/cli/env) | @@ -229,26 +245,25 @@ For declarative branch policy, neon config init scaffolds a starter [neon.ts](ht | Mint / revoke API keys | `neon api-keys …` | [api-keys](https://neon.com/docs/cli/api-keys) | | Multi-account credentials | `neon profile …` | [profile](https://neon.com/docs/cli/profile) | | Schema diff | `neon diff [branch]` | [diff](https://neon.com/docs/cli/diff) | -| Any API route | `neon api ` | [api](https://neon.com/docs/cli/api) | +| Any API route (agent fallback) | `neon api ` | [api](https://neon.com/docs/cli/api) | | Postgres diagnostics | `neon inspect db ` | [inspect](https://neon.com/docs/cli/inspect) | | Snapshots | `neon snapshots …` | [snapshots](https://neon.com/docs/cli/snapshots) | | Auth management | `neon neon-auth …` | [neon-auth](https://neon.com/docs/cli/neon-auth) | | Data API | `neon data-api …` | [data-api](https://neon.com/docs/cli/data-api) | | SQL shell | `neon psql` | [psql](https://neon.com/docs/cli/psql) | -| Agent / MCP setup | `npx neon@latest init` | [init](https://neon.com/docs/cli/init) | ## What to put in AGENTS.md -If you want coding agents to use the branch-first loop by default, a short rule is enough: +Drop this into your project's AGENTS.md (or Cursor rules) so coding agents default to the branch-first loop: +``` When starting a feature, run `neon checkout ` alongside `git checkout -b`. Prefer project-scoped API keys (`neon api-keys create --project-id …`) for automation. Use `neon diff` before merging schema changes, and `neon inspect db` for read-only Postgres diagnostics. -Install current Neon skills so the agent knows the new commands: +Install current Neon skills so the agent knows the commands: -``` -npx neon@latest init +neon skills ``` From 974886477e7f6e315f55092d642368ae5392e0da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?carlota=E2=98=80=EF=B8=8F?= <82476502+carlotas19@users.noreply.github.com> Date: Tue, 25 Aug 2026 13:52:26 -0700 Subject: [PATCH 4/4] Improve description of neon api command usage Rephrase explanation of the 'neon api' command for clarity and conciseness. --- content/blog/posts/just-landed-in-the-neon-cli.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/blog/posts/just-landed-in-the-neon-cli.md b/content/blog/posts/just-landed-in-the-neon-cli.md index 5a219dcc5b..c6f0e616a8 100644 --- a/content/blog/posts/just-landed-in-the-neon-cli.md +++ b/content/blog/posts/just-landed-in-the-neon-cli.md @@ -175,7 +175,7 @@ neon diff main ## Call any Neon API route with neon api (agent fallback) -Most humans will never need this. Coding agents reach for [`neon api`](https://neon.com/docs/cli/api) when they need an API route that doesn't have a dedicated CLI command yet - a fallback for automation, not day-to-day terminal work. It uses your existing CLI login: +Most humans will never need this - this is a fallback for agent automation. Coding agents can now reach for [`neon api`](https://neon.com/docs/cli/api) when they need an API route that doesn't have a dedicated CLI command yet. It uses your existing CLI login: ``` neon api --list @@ -183,8 +183,6 @@ neon api /projects -Q org_id=org-cool-darkness-12345678 neon api /projects/late-frost-12345678/branches -X POST -F branch.name=dev ``` --F branch.name=dev builds nested JSON. Bodies can also come from -d @file. - ## Snapshots from the terminal: neon snapshots [Point-in-time branch backups](https://neon.com/docs/cli/snapshots) are now first-class in the CLI: