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,

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 - full onboarding: OAuth, API key, MCP server, editor extension, and agent skills
• neon mcp - MCP server only
• neon 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:

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 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):

neon env pull --service ai-gateway --service postgres

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:

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, 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

neon open

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:

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 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:

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 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 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 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:

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 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:

neon projects create --name my-app --pg-version 17

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

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 <branch-name>` 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