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..c6f0e616a8 --- /dev/null +++ b/content/blog/posts/just-landed-in-the-neon-cli.md @@ -0,0 +1,267 @@ +--- +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: >- + https://cdn.neonapi.io/public/images/pages/blog/just-landed-in-the-neon-cli/neon-just-landed.jpg + alt: Just landed in the Neon CLI +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: >- + 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 + +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: + +``` +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): + +``` +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 +``` + +## 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 + +``` +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 (agent fallback) + +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 +neon api /projects -Q org_id=org-cool-darkness-12345678 +neon api /projects/late-frost-12345678/branches -X POST -F branch.name=dev +``` + +## 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) | +| 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) | +| 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 (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) | + +## What to put in AGENTS.md + +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 commands: + +neon skills +```