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:
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),
For agents, set up skills and the MCP server in one shot:
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:
-
full onboarding: OAuth, API key, MCP server, editor extension, and agent skills
neon init -
MCP server only
neon mcp -
agent skills only
neon skills
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: neon 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 pins the active branch in that context, the same way you'd switch a git branch.
neon env pull 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 file is left alone.
A recent refinement - pull only the services you name (postgres, auth, data-api, object-storage, or ai-gateway):
Debug Postgres via neon inspect db #
This diagnostics tool bundles read-only diagnostics against Postgres stats and catalogs, with connection resolution handled by the CLI:
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,deep dive,changelog).
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
To open the linked project's dashboard in your browser.
See the pinned branch: neon status #
This command prints the branch in .neon with no network call, so it's safe for shell prompts:
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
A project-scoped key 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: --mint signs in once, stores only the minted key, and leaves no browser session behind.
Print schema diffs with neon diff #
neon 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
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 when they need an API route that doesn't have a dedicated CLI command yet. It uses your existing CLI login:
Snapshots from the terminal: neon snapshots #
Point-in-time branch backups are now first-class in the CLI: 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:
Manage the Data API via neon data-api
You can also provision and manage the Data API (create, get, update, refresh-schema, delete).
neon psql without a local psql install
neon 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 now accepts more up-front control - e.g. you can specify Postgres version, protected branches, logical replication:
For declarative branch policy, neon config init scaffolds a starter neon.ts and installs @neon/config / @neon/env. neon link can offer this as a final step. Backend service commands 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 |
|
neon auth
[auth](https://neon.com/docs/cli/auth)`neon init`
[init](https://neon.com/docs/cli/init)`neon mcp`
[mcp](https://neon.com/docs/cli/mcp)`neon skills`
[skills](https://neon.com/docs/cli/skills)`neon link`
[link](https://neon.com/docs/cli/link)`neon checkout <name>`
[checkout](https://neon.com/docs/cli/checkout)`neon env pull [--service …]`
[env](https://neon.com/docs/cli/env)`neon open`
[open](https://neon.com/docs/cli/open)`neon api-keys …`
[api-keys](https://neon.com/docs/cli/api-keys)`neon profile …`
[profile](https://neon.com/docs/cli/profile)`neon diff [branch]`
[diff](https://neon.com/docs/cli/diff)`neon api <path>`
[api](https://neon.com/docs/cli/api)`neon inspect db <check>`
[inspect](https://neon.com/docs/cli/inspect)`neon snapshots …`
[snapshots](https://neon.com/docs/cli/snapshots)`neon neon-auth …`
[neon-auth](https://neon.com/docs/cli/neon-auth)`neon data-api …`
[data-api](https://neon.com/docs/cli/data-api)`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: