Neon Release Notes

A new Console layout for the Neon backend

The Console sidebar has a new shape. Every branch-level Neon backend service now sits at the same level.

Postgres database is everything that was in the sidebar before: Tables, SQL Editor, Backup & Restore, Computes, Data API, Roles, and Databases, now under one collapsible item.

Auth, Object storage, Functions, and AI Gateway backend services sit alongside it as siblings.

Above that section, the sidebar separates what belongs to project (Dashboard, Branches, Integrations, Settings) from what belongs to the branch (Overview, Credentials, Monitoring, Child branches). The branch picker sits between them, so it's clear which branch you're looking at when you open a service.

Overview is now a summary of the branch you have selected. It lists each backend service with its status, so you can see what the branch actually has enabled without opening each one:

Each service shows whether it's enabled on the branch, so the page doubles as a list of what you can still add.

MORE REGIONS FOR BACKEND SERVICES COMING SOON

Object Storage, Functions, and the AI Gateway services are available only in AWS US East (Ohio) (aws-us-east-2). More regions are coming soon.

More models on the AI Gateway

We've expanded the models available through the Neon AI Gateway, including Kimi K3, GLM-5.2, Inkling, and new additions to the Gemini and GPT families.

The catalog now spans frontier and open-weight models from OpenAI, Anthropic, Google, Meta, Moonshot AI, Alibaba, Zhipu AI, and Thinking Machines. One credential and one base URL reach all of them, so trying a different model means changing a string rather than signing up with another provider:

curl -X POST "$NEON_AI_GATEWAY_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "kimi-k3", "messages": [{"role": "user", "content": "What is Neon?"}]}'

Browse the full catalog in the model reference, where you can filter by provider or open weights and open any model for a copy-paste quickstart. To see what your own project can reach right now, call GET /v1/models.

SET UP THE NEON BACKEND WITH YOUR AI AGENT

To build with the beta services including AI Gateway, install the Neon agent skills so your assistant knows how to provision and wire them up:

npx neon@latest init

Then ask your assistant to get started with Neon. See the backend beta guide for access and setup, or How a Neon backend fits together for a tour of all five capabilities.

Project-level permissions for all orgs

Last week we introduced project-level permissions to newly created organizations. Existing organizations are now supported, so every team on Neon has the four organization roles (Admin, Editor, Viewer, and Collaborator) and per-project permissions.

See Neon now has per-project permissions for the annoucement, and User permissions for the complete documentation.

GET STARTED WITH PROJECT PERMISSIONS

Go from everyone-sees-everything to scoped access in about five minutes. Read the guide.

API keys and multiple accounts in the Neon CLI

There are two new additions to the Neon CLI that go together: api-keys mints credentials, and profile stores them and switches between them. Together they let you give an agent a credential that reaches exactly one project, or work across a personal account and a work organization without juggling config directories.

NEW TO THE NEON CLI?

Install it with npm install -g neon, then authenticate with neon auth. See the install guide and CLI quickstart to get going.

Manage API keys with neon api-keys

Manage API keys with neon api-keys

Minting a key used to mean opening the Console or hand-rolling a neon api request. neon api-keys now covers listing, creating, and revoking keys at every scope:

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

Project-scoped keys are the reason this matters. A key created with --project-id can't create projects, can't mint more keys, and can't see any other project, which makes it safe to hand to an agent or a CI job instead of sharing your account.

See the neon api-keys reference neon api-keys reference and Manage API keys for key types and permissions.

Use more than one account with neon profile

Use more than one account with neon profile

The CLI could only hold one account at a time, so anyone working across two built their own workaround out of --config-dir and shell aliases. A profile is a name pointing at a credentials file, selected per invocation with --profile or NEON_PROFILE :

neon auth --profile work # create or re-authenticate
neon deploy --profile work # use it
neon profile create ci --mint --project-id green-breeze-12345678 # or hold a scoped key, no browser

A profile can hold a browser sign-in or an API key, which is where it meets the scoped keys above. --mint signs in once, keeps only the minted key, and signs the session back out, so afterwards nothing about the profile can open a browser.

The CLI also now stores its configuration in $XDG_CONFIG_HOME/neon , or ~/.config/neon if that isn't set. A pre-existing neonctl directory is still read in place, so there's no migration step.

See the neon profile reference neon profile reference for the full command set and for how --profile resolves against NEON_API_KEY .

New NAT gateway IPs and VPC endpoint services in Europe (Frankfurt)

We've expanded infrastructure capacity in the AWS Europe (Frankfurt) region (eu-central-1) with new NAT gateway IP addresses and new VPC endpoint service addresses for Private Networking.

UPDATE YOUR IP ALLOWLISTS

If you have IP allowlists on external systems that Neon connects to, update those allowlists to include the new NAT gateway addresses. Connections may be affected intermittently if traffic routes through non-allowlisted NAT gateways.

If you use Private Networking in eu-central-1 , you can now use the additional VPC endpoint service addresses for enhanced capacity and reliability. See the Regions documentation for the complete list of NAT gateway IPs and the Private Networking guide for VPC endpoint service addresses by region.

A new Console layout for the Neon backend

The Console sidebar has a new shape. Every branch-level Neon backend service now sits at the same level.

• Postgres database is everything that was in the sidebar before: Tables, SQL Editor, Backup & Restore, Computes, Data API, Roles, and Databases, now under one collapsible item.
• Auth, Object storage, Functions, and AI Gateway backend services sit alongside it as siblings.

Above that section, the sidebar separates what belongs to project (Dashboard, Branches, Integrations, Settings) from what belongs to the branch (Overview, Credentials, Monitoring, Child branches). The branch picker sits between them, so it's clear which branch you're looking at when you open a service.

Overview is now a summary of the branch you have selected. It lists each backend service with its status, so you can see what the branch actually has enabled without opening each one:

Each service shows whether it's enabled on the branch, so the page doubles as a list of what you can still add.

MORE REGIONS FOR BACKEND SERVICES COMING SOON

Object Storage, Functions, and the AI Gateway services are available only in AWS US East (Ohio) (aws-us-east-2). More regions are coming soon.

More models on the AI Gateway

We've expanded the models available through the Neon AI Gateway, including Kimi K3, GLM-5.2, Inkling, and new additions to the Gemini and GPT families.

The catalog now spans frontier and open-weight models from OpenAI, Anthropic, Google, Meta, Moonshot AI, Alibaba, Zhipu AI, and Thinking Machines. One credential and one base URL reach all of them, so trying a different model means changing a string rather than signing up with another provider:

curl -X POST "$NEON_AI_GATEWAY_BASE_URL/v1/chat/completions" \
-H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"model": "kimi-k3", "messages": [{"role": "user", "content": "What is Neon?"}]}'

Browse the full catalog in the model reference, where you can filter by provider or open weights and open any model for a copy-paste quickstart. To see what your own project can reach right now, call GET /v1/models.

SET UP THE NEON BACKEND WITH YOUR AI AGENT

To build with the beta services including AI Gateway, install the Neon agent skills so your assistant knows how to provision and wire them up:

npx neon@latest init

Then ask your assistant to get started with Neon. See the backend beta guide for access and setup, or How a Neon backend fits together for a tour of all five capabilities.

Project-level permissions for all orgs

Last week we introduced project-level permissions to newly created organizations. Existing organizations are now supported, so every team on Neon has the four organization roles (Admin, Editor, Viewer, and Collaborator) and per-project permissions.

See Neon now has per-project permissions for the annoucement, and User permissions for the complete documentation.

GET STARTED WITH PROJECT PERMISSIONS

Go from everyone-sees-everything to scoped access in about five minutes. Read the guide.

API keys and multiple accounts in the Neon CLI

There are two new additions to the Neon CLI that go together: api-keys mints credentials, and profile stores them and switches between them. Together they let you give an agent a credential that reaches exactly one project, or work across a personal account and a work organization without juggling config directories.

NEW TO THE NEON CLI?

Install it with npm install -g neon, then authenticate with neon auth. See the install guide and CLI quickstart to get going.

Manage API keys with neon api-keys

Minting a key used to mean opening the Console or hand-rolling a neon api request. neon api-keys now covers listing, creating, and revoking keys at every scope:

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

Project-scoped keys are the reason this matters. A key created with --project-id can't create projects, can't mint more keys, and can't see any other project, which makes it safe to hand to an agent or a CI job instead of sharing your account.

See the neon api-keys reference and Manage API keys for key types and permissions.

Use more than one account with neon profile

The CLI could only hold one account at a time, so anyone working across two built their own workaround out of --config-dir and shell aliases. A profile is a name pointing at a credentials file, selected per invocation with --profile or NEON_PROFILE:

neon auth --profile work # create or re-authenticate
neon deploy --profile work # use it
neon profile create ci --mint --project-id green-breeze-12345678 # or hold a scoped key, no browser

A profile can hold a browser sign-in or an API key, which is where it meets the scoped keys above. --mint signs in once, keeps only the minted key, and signs the session back out, so afterwards nothing about the profile can open a browser.

The CLI also now stores its configuration in $XDG_CONFIG_HOME/neon, or ~/.config/neon if that isn't set. A pre-existing neonctl directory is still read in place, so there's no migration step.

See the neon profile reference for the full command set and for how --profile resolves against NEON_API_KEY.

New NAT gateway IPs and VPC endpoint services in Europe (Frankfurt)

We've expanded infrastructure capacity in the AWS Europe (Frankfurt) region (eu-central-1) with new NAT gateway IP addresses and new VPC endpoint service addresses for Private Networking.

UPDATE YOUR IP ALLOWLISTS

If you have IP allowlists on external systems that Neon connects to, update those allowlists to include the new NAT gateway addresses. Connections may be affected intermittently if traffic routes through non-allowlisted NAT gateways.

If you use Private Networking in eu-central-1, you can now use the additional VPC endpoint service addresses for enhanced capacity and reliability. See the Regions documentation for the complete list of NAT gateway IPs and the Private Networking guide for VPC endpoint service addresses by region.

Project-level permissions

A feature you've been asking for is finally here. Until now, a person's access applied across your entire organization. We're excited to bring project-level permissions to Neon, so you can now grant people and agents access on individual projects, giving them only what they need where they need it. On any project, you can make someone a Viewer to see its resources, an Editor to change them, or an Admin to manage access and the project itself.

AVAILABILITY

The new model is available now for newly created organizations and will roll out to existing organizations soon.

Access works in two layers. When both apply, a user keeps the higher level of access:

• Organization roles set a baseline across every project. There are now four: Admin (full control), Editor (work in every project, but can't delete or transfer them), Viewer (read-only), and Collaborator (no access until granted specific projects).
• Per-project permissions raise that baseline on specific projects. Grant a member Viewer (read-only), Editor (connect, query, and edit resources), or Admin (manage access, settings, and the project lifecycle) on any project from Settings → Project permissions.

For example, give a contractor the Collaborator role, which grants nothing by default, then Editor on just the two projects they work on. Or give a teammate Viewer across the organization and Admin on the one project they own.

You can manage the same access through the Neon API, so an orchestrator can provision a project and grant a worker agent scoped access to it:

curl --request PUT \
--url 'https://console.neon.tech/api/v2/projects/{project_id}/members/{member_id}/role' \
--header 'authorization: Bearer $ORG_API_KEY' \
--header 'content-type: application/json' \
--data '{"role": "editor"}'

The CLI doesn't have a dedicated command yet, but you can call the same route with the neon api passthrough.

What changes for existing organizations

When your organization is migrated, it moves to the new model automatically, and everyone keeps the access they have today. No action is required:

• Admins stay Admins.
• Members become Editors, with the same access under the new name.
• Project creators become Admin on the projects they created.
• People with project-share access become Editor on the projects shared with them.

The older project collaboration feature is being replaced by the new Collaborator role plus per-project permissions.

See User permissions for roles, per-project levels, and how the two layers combine.

New guides for building on the Neon backend

Two new guides show how to combine the Neon backend services, from long-running compute to LLM access, all in a single project that branches with your data:

• Build durable background workflows with Inngest and Neon Functions: run a multi-step lead-enrichment pipeline on Neon Functions, with each step checkpointed so a failure retries just that step, and an executive summary generated through the Neon AI Gateway.
• Build an LLM proxy with Neon Functions, Neon AI Gateway, and Managed Better Auth: host a secure proxy on Neon Functions that keeps your LLM keys off the browser, authenticates users with Managed Better Auth, enforces per-user rate limits in Postgres, and streams responses from the AI Gateway.

SET UP THE NEON BACKEND WITH YOUR AI AGENT

The backend services (Object Storage, Functions, and AI Gateway) are in beta in AWS us-east-2. To build with them, install the Neon agent skills so your assistant knows how to provision and wire them up:

npx neon@latest init

Then ask your assistant to get started with Neon. See the backend beta guide for access and setup.

Project-level permissions

A feature you've been asking for is finally here. Until now, a person's access applied across your entire organization. We're excited to bring project-level permissions to Neon, so you can now grant people and agents access on individual projects, giving them only what they need where they need it. On any project, you can make someone a Viewer to see its resources, an Editor to change them, or an Admin to manage access and the project itself.

AVAILABILITY

The new model is available now for newly created organizations and will roll out to existing organizations soon.

Access works in two layers. When both apply, a user keeps the higher level of access:

• Organization roles set a baseline across every project. There are now four: Admin (full control), Editor (work in every project, but can't delete or transfer them), Viewer (read-only), and Collaborator (no access until granted specific projects).
• Per-project permissions raise that baseline on specific projects. Grant a member Viewer (read-only), Editor (connect, query, and edit resources), or Admin (manage access, settings, and the project lifecycle) on any project from Settings → Project permissions.

For example, give a contractor the Collaborator role, which grants nothing by default, then Editor on just the two projects they work on. Or give a teammate Viewer across the organization and Admin on the one project they own.

You can manage the same access through the Neon API, so an orchestrator can provision a project and grant a worker agent scoped access to it:

curl --request PUT \
  --url 'https://console.neon.tech/api/v2/projects/{project_id}/members/{member_id}/role' \
  --header 'authorization: Bearer $ORG_API_KEY' \
  --header 'content-type: application/json' \
  --data '{"role": "editor"}'

The CLI doesn't have a dedicated command yet, but you can call the same route with the neon api passthrough.

What changes for existing organizations

When your organization is migrated, it moves to the new model automatically, and everyone keeps the access they have today. No action is required:

• Admins stay Admins.
• Members become Editors, with the same access under the new name.
• Project creators become Admin on the projects they created.
• People with project-share access become Editor on the projects shared with them.

The older project collaboration feature is being replaced by the new Collaborator role plus per-project permissions.

See User permissions for roles, per-project levels, and how the two layers combine.

New guides for building on the Neon backend

Two new guides show how to combine the Neon backend services, from long-running compute to LLM access, all in a single project that branches with your data:

• Build durable background workflows with Inngest and Neon Functions: run a multi-step lead-enrichment pipeline on Neon Functions, with each step checkpointed so a failure retries just that step, and an executive summary generated through the Neon AI Gateway.
• Build an LLM proxy with Neon Functions, Neon AI Gateway, and Managed Better Auth: host a secure proxy on Neon Functions that keeps your LLM keys off the browser, authenticates users with Managed Better Auth, enforces per-user rate limits in Postgres, and streams responses from the AI Gateway.

SET UP THE NEON BACKEND WITH YOUR AI AGENT

The backend services (Object Storage, Functions, and AI Gateway) are in beta in AWS us-east-2. To build with them, install the Neon agent skills so your assistant knows how to provision and wire them up:

npx neon@latest init

Then ask your assistant to get started with Neon. See the backend beta guide for access and setup.

More with Lakebase Search

Lakebase Search adds scalable vector, keyword, and hybrid search to Postgres through the lakebase_vector and lakebase_text extensions. This week, two new resources show it in action:

• Case study: CommSync runs text, vector, and hybrid search on Postgres with Lakebase Search. See how a unified business inbox powers its main inbox (BM25 text search), AI assistant (semantic search), and command palette (hybrid search with Reciprocal Rank Fusion) from a single database, cutting query latency from 19.5 seconds to 18.6 milliseconds.
• Guide: Build image search over CLIP embeddings with Lakebase Search. Search a Flickr30k corpus by text, by image, and by caption from one vector(512) column, using the lakebase_ann index (IVF + RaBitQ) that builds 50 to 100 times faster than HNSW.

To get started, load the Lakebase Search preload libraries, then create the extensions:

CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;
CREATE EXTENSION IF NOT EXISTS lakebase_text CASCADE;

Fixes & improvements

Spending notifications

Neon MCP Server

Drizzle Studio

Debug Postgres from the terminal with neon inspect db

You can now run read-only Postgres diagnostics straight from the Neon CLI with neon inspect db. Each subcommand runs a single, known-good query against Postgres' own statistics and catalog views, then prints a clean table (or JSON/YAML for scripting). There's no connection string to assemble and no catalog view to recall: the CLI resolves the endpoint, role, password, and database through the same Neon API the SDK uses, so you name a diagnostic and go.

NEW TO THE NEON CLI?

Install it with npm install -g neon, then authenticate with neon auth. See the install guide and CLI quickstart to get going.

Fourteen subcommands cover the questions you actually ask when something is slow, grouped by what you're chasing:

• Size and storage: table-sizes, index-sizes, bloat
• Indexes and scans: unused-indexes, seq-scans
• Live activity and contention: long-running-queries, locks
• Query workload: outliers, calls (from pg_stat_statements)
• Maintenance: vacuum-stats
• Replication: replication-slots, subscriptions
• Neon cache debugging: lfc-hit-rate, working-set

Every command is read-only, scoped to the columns that answer the question, and capped where results can get large. That makes it as safe to hand to an agent as it is to run yourself. Point it at a linked project, or at any Postgres database with --db-url :

neon link # or: neon set-context --project-id
neon inspect db bloat
neon inspect db outliers --db-url postgres://:@:5432/

See the neon inspect reference for the full command reference, and read the deep dive on our blog.

Manage snapshots from the Neon CLI

The Neon CLI now has a first-class neon snapshots command group. Snapshots are point-in-time backups of a branch, and they were previously only available in the Console and REST API. You can manage the full lifecycle from your terminal:

• neon snapshots list and neon snapshots get to see your snapshots.
• neon snapshots create to snapshot a branch, optionally at a point in time with --timestamp or --lsn.
• neon snapshots update and neon snapshots delete to rename, re-expire, or remove a snapshot.
• neon snapshots restore to restore a snapshot into a branch, with a preview step so you can inspect the result before running neon snapshots finalize to commit it.

For example, snapshot a branch before a risky migration, then restore it into a new branch if you need to roll back:

neon snapshots create --branch main --name pre-migration
neon snapshots list
neon snapshots restore pre-migration --name recovered

You can also view and set a branch's automatic backup schedule with neon snapshots schedule get and neon snapshots schedule set. Automated backup schedules are available on paid plans, except for the Agent plan. See the neon snapshots reference for the full list of subcommands.

Create projects with more control from the CLI

neon projects create now accepts flags to configure a project up front: choose the PostgreSQL version, create protected branches, and enable logical replication.

See the neon projects reference for the full list of flags.

Query Functions and Storage logs from the Neon MCP server

Functions and Object Storage are core pieces of the Neon backend: serverless compute and S3-compatible storage that branch with your database in the same project. You can now query logs from both services directly through the Neon MCP server, so your AI assistant can investigate a failure without leaving your editor. Three new read-only tools make up the observability category:

• query_logs: filter logs by source, service, severity, or a text match over a time window (or drop down to raw LogQL for full control).
• list_log_fields: discover the fields you can filter on.
• list_log_field_values: list the values a field takes, to ground your filters.

Once the MCP server is connected, ask your assistant in plain language:

Why did my function error in the last hour? Check the logs.

The same logs are documented under Neon Functions logs and object storage logs.

New guides for building on the Neon backend

Two new guides show how to build on the Neon backend, from declaring your services to shipping a real app:

• Manage Neon projects with neon.ts: use Neon's native TypeScript configuration to provision Postgres, Managed Better Auth, and the Data API, manage branch compute, and generate type-safe environment variables, all from one file that branches with your data.
• Build a Discord bot with Neon Functions and Neon AI Gateway: put Functions and the AI Gateway to work in a single project, with AI chat and image generation hosted next to your database.

SET UP THE NEON BACKEND WITH YOUR AI AGENT

The backend services (Object Storage, Functions, and AI Gateway) are in beta in AWS us-east-2. To build with them, install the Neon agent skills so your assistant knows how to provision and wire them up:

npx neon@latest init

Then ask your assistant to get started with Neon. See the backend beta guide for access and setup.

Debug Postgres from the terminal with neon inspect db

You can now run read-only Postgres diagnostics straight from the Neon CLI with neon inspect db. Each subcommand runs a single, known-good query against Postgres' own statistics and catalog views, then prints a clean table (or JSON/YAML for scripting). There's no connection string to assemble and no catalog view to recall: the CLI resolves the endpoint, role, password, and database through the same Neon API the SDK uses, so you name a diagnostic and go.

NEW TO THE NEON CLI?

Install it with npm install -g neon, then authenticate with neon auth. See the install guide and CLI quickstart to get going.

Fourteen subcommands cover the questions you actually ask when something is slow, grouped by what you're chasing:

• Size and storage: table-sizes, index-sizes, bloat
• Indexes and scans: unused-indexes, seq-scans
• Live activity and contention: long-running-queries, locks
• Query workload: outliers, calls (from pg_stat_statements)
• Maintenance: vacuum-stats
• Replication: replication-slots, subscriptions
• Neon cache debugging: lfc-hit-rate, working-set

Every command is read-only, scoped to the columns that answer the question, and capped where results can get large. That makes it as safe to hand to an agent as it is to run yourself. Point it at a linked project, or at any Postgres database with --db-url:

neon link # or: neon set-context --project-id <project-id>
neon inspect db bloat

neon inspect db outliers --db-url postgres://<user>:<password>@<host>:5432/<dbname>

See the neon inspect reference for the full command reference, and read the deep dive on our blog.

Manage snapshots from the Neon CLI

The Neon CLI now has a first-class neon snapshots command group. Snapshots are point-in-time backups of a branch, and they were previously only available in the Console and REST API. You can manage the full lifecycle from your terminal:

• neon snapshots list and neon snapshots get to see your snapshots.
• neon snapshots create to snapshot a branch, optionally at a point in time with --timestamp or --lsn.
• neon snapshots update and neon snapshots delete to rename, re-expire, or remove a snapshot.
• neon snapshots restore to restore a snapshot into a branch, with a preview step so you can inspect the result before running neon snapshots finalize to commit it.

For example, snapshot a branch before a risky migration, then restore it into a new branch if you need to roll back:

neon snapshots create --branch main --name pre-migration
neon snapshots list
neon snapshots restore pre-migration --name recovered

You can also view and set a branch's automatic backup schedule with neon snapshots schedule get and neon snapshots schedule set. Automated backup schedules are available on paid plans, except for the Agent plan. See the neon snapshots reference for the full list of subcommands.

Create projects with more control from the CLI

neon projects create now accepts flags to configure a project up front: choose the PostgreSQL version, create protected branches, and enable logical replication.

neon projects create --name my-app --pg-version 17
neon branches create --project-id <project-id> --name production --protected
neon projects update <project-id> --enable-logical-replication --yes

See the neon projects reference for the full list of flags.

Query Functions and Storage logs from the Neon MCP server

Functions and Object Storage are core pieces of the Neon backend: serverless compute and S3-compatible storage that branch with your database in the same project. You can now query logs from both services directly through the Neon MCP server, so your AI assistant can investigate a failure without leaving your editor. Three new read-only tools make up the observability category:

• query_logs: filter logs by source, service, severity, or a text match over a time window (or drop down to raw LogQL for full control).
• list_log_fields: discover the fields you can filter on.
• list_log_field_values: list the values a field takes, to ground your filters.

Once the MCP server is connected, ask your assistant in plain language:

Why did my function error in the last hour? Check the logs.

The same logs are documented under Neon Functions logs and object storage logs.

New guides for building on the Neon backend

Two new guides show how to build on the Neon backend, from declaring your services to shipping a real app:

• Manage Neon projects with neon.ts: use Neon's native TypeScript configuration to provision Postgres, Managed Better Auth, and the Data API, manage branch compute, and generate type-safe environment variables, all from one file that branches with your data.
• Build a Discord bot with Neon Functions and Neon AI Gateway: put Functions and the AI Gateway to work in a single project, with AI chat and image generation hosted next to your database.

SET UP THE NEON BACKEND WITH YOUR AI AGENT

The backend services (Object Storage, Functions, and AI Gateway) are in beta in AWS us-east-2. To build with them, install the Neon agent skills so your assistant knows how to provision and wire them up:

npx neon@latest init

Then ask your assistant to get started with Neon. See the backend beta guide for access and setup.

Neon backend for apps and agents is now in beta

Neon Object Storage, Functions, and AI Gateway have graduated from private preview to beta. Everyone can start building a complete backend on new or existing projects in AWS US East (Ohio) today.

Declare your whole backend in one neon.ts file, and it branches with your data. Fork a branch and you get an isolated copy of your database, files, functions, and gateway.

Object Storage

S3-compatible object storage that branches with your database.

Functions

Long-running serverless compute that runs alongside your database.

AI Gateway

One API for frontier and open-source models, built into your project.

New to the Neon backend? Start with the beta guide, see how the pieces fit together, or build one end to end with the full backend quickstart. For the vision behind the platform, read the announcement blog post.

ONE-SHOT YOUR BACKEND WITH AN AI AGENT

Install the beta agent skills:

npx neon@latest init --preview

Then build your backend from a single prompt:

Set up a Neon backend for my app with Postgres, object storage, functions, and AI gateway

Your agent provisions the services, declares them in neon.ts, and wires them into your app.

New TypeScript SDK for the Neon API

We're introducing @neon/sdk 1.1, the best way to work with the Neon API from TypeScript. It's fetch-based, zero-dependency, and generated from our OpenAPI spec, with an ergonomic layer on top. It covers the whole Neon Platform API: projects, branches, databases, and our new backend services (Object Storage, Functions, and AI Gateway). It replaces @neondatabase/api-client as the recommended client, though the legacy package still works.

The ergonomic layer matters most for the multi-step provisioning workflows that might take you or your agent a few attempts to get right (for example, create a project, wait for it to be ready, then create a branch and hand back a connection string).

createNeonClient({ apiKey }) gives you namespaced methods (neon.projects, neon.storage, neon.functions, neon.aiGateway, and more), typed { data, error } results, and workflow helpers like createAndConnect. Any method takes { waitForReadiness: true } to block until provisioning finishes, and a raw layer exposes every endpoint.

Read the announcement blog post for the full story, or see the TypeScript SDK documentation and migration guide for setup, API reference, and moving from @neondatabase/api-client.

Passkey support

You can now sign in to Neon with a passkey instead of a 2FA code. Add a passkey from Account settings and use your device's built-in biometrics, like Touch ID or Windows Hello, or a security key to verify it's you. Passkeys satisfy organization-level 2FA requirements, so admins can let members enroll in either 2FA or a passkey to comply. See Manage your Neon account for setup steps.

Git-style diffs in the Neon CLI

New neon diff command

We've added a top-level diff command to the Neon CLI, letting you (and your agents) quickly see schema changes between your current branch and any other branch you specify. It fits into a branch-first development workflow alongside neon link, neon checkout, neon status, and neon deploy.

1. neon link: link to a Neon project
2. neon checkout dev-1: create/checkout a dev branch
3. Do the dev work
4. neon diff main: sanity check the schema changes made against main

Want your agents to use neon diff? Install the Neon agent skills so your assistant has current knowledge of the CLI and reaches for the command on its own:

npx neon@latest init

Config commands now show the same diff

neon.ts is the TypeScript config file that declares your Neon backend: which services are on (Postgres, Auth, Data API, Object Storage, Functions) and your branch settings (compute size, TTL, protected). The config commands reconcile that file with what's actually live:
neon config plan previews the changes,
neon config apply makes them, and
neon deploy applies and provisions in one step.

These commands now report their changes as a git diff instead of tables so you can see exactly what will change before you confirm:

If apply finds a setting that already differs on the branch, it shows the current value too and stops without changing anything until you re-run with --update-existing.

New NAT gateway IPs and VPC endpoint services in US East (Ohio), Europe (London), and Asia Pacific (Singapore)

We've expanded infrastructure capacity in the AWS US East (Ohio) (us-east-2), Europe (London) (eu-west-2), and Asia Pacific (Singapore) (ap-southeast-1) regions with new NAT gateway IP addresses and new VPC endpoint service addresses for Private Networking.

UPDATE YOUR IP ALLOWLISTS

If you have IP allowlists on external systems that Neon connects to, update those allowlists to include the new NAT gateway addresses. Connections may be affected intermittently if traffic routes through non-allowlisted NAT gateways.

If you use Private Networking in these regions, you can now use the additional VPC endpoint service addresses for enhanced capacity and reliability. See the Regions documentation for the complete list of NAT gateway IPs and the Private Networking guide for VPC endpoint service addresses by region.

Neon backend for apps and agents is now in beta

Neon Object Storage, Functions, and AI Gateway have graduated from private preview to beta. Everyone can start building a complete backend on new or existing projects in AWS US East (Ohio) today.

Declare your whole backend in one neon.ts file, and it branches with your data. Fork a branch and you get an isolated copy of your database, files, functions, and gateway.

• Object Storage: S3-compatible object storage that branches with your database.
• Functions: Long-running serverless compute that runs alongside your database.
• AI Gateway: One API for frontier and open-source models, built into your project.

New to the Neon backend? Start with the beta guide, see how the pieces fit together, or build one end to end with the full backend quickstart. For the vision behind the platform, read the announcement blog post.

ONE-SHOT YOUR BACKEND WITH AN AI AGENT

Install the beta agent skills:

npx neon@latest init --preview

Then build your backend from a single prompt:

Set up a Neon backend for my app with Postgres, object storage, functions, and AI gateway

Your agent provisions the services, declares them in neon.ts, and wires them into your app.

New TypeScript SDK for the Neon API

We're introducing @neon/sdk 1.1, the best way to work with the Neon API from TypeScript. It's fetch-based, zero-dependency, and generated from our OpenAPI spec, with an ergonomic layer on top. It covers the whole Neon Platform API: projects, branches, databases, and our new backend services (Object Storage, Functions, and AI Gateway). It replaces @neondatabase/api-client as the recommended client, though the legacy package still works.

The ergonomic layer matters most for the multi-step provisioning workflows that might take you or your agent a few attempts to get right (for example, create a project, wait for it to be ready, then create a branch and hand back a connection string).

createNeonClient({ apiKey }) gives you namespaced methods (neon.projects, neon.storage, neon.functions, neon.aiGateway, and more), typed { data, error } results, and workflow helpers like createAndConnect. Any method takes { waitForReadiness: true } to block until provisioning finishes, and a raw layer exposes every endpoint.

npm install @neon/sdk

import { createNeonClient } from "@neon/sdk";
const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY! });

// Workflow helper: create, poll until ready, return a connection string
const { data, error } = await neon.projects.createAndConnect({ name: "my-app" });
if (error) throw error;
const { project, connectionString } = data;

// Or wait on any mutation with waitForReadiness
const { data: branch, error: branchError } = await neon.branches.create(
  project.id,
  { name: "preview" },
  { waitForReadiness: true }
);
if (branchError) throw branchError;

// The new backend services are namespaced too
await neon.storage.buckets.create(
  project.id,
  branch.id,
  { name: "uploads" }
);

Read the announcement blog post for the full story, or see the TypeScript SDK documentation and migration guide for setup, API reference, and moving from @neondatabase/api-client.

Passkey support

You can now sign in to Neon with a passkey instead of a 2FA code. Add a passkey from Account settings and use your device's built-in biometrics, like Touch ID or Windows Hello, or a security key to verify it's you. Passkeys satisfy organization-level 2FA requirements, so admins can let members enroll in either 2FA or a passkey to comply. See Manage your Neon account for setup steps.

Git-style diffs in the Neon CLI

New neon diff command

We've added a top-level diff command to the Neon CLI, letting you (and your agents) quickly see schema changes between your current branch and any other branch you specify. It fits into a branch-first development workflow alongside neon link, neon checkout, neon status, and neon deploy.

1. neon link: link to a Neon project
2. neon checkout dev-1: create/checkout a dev branch
3. Do the dev work
4. neon diff main: sanity check the schema changes made against main

Want your agents to use neon diff? Install the Neon agent skills so your assistant has current knowledge of the CLI and reaches for the command on its own:

npx neon@latest init

Config commands now show the same diff

neon.ts is the TypeScript config file that declares your Neon backend: which services are on (Postgres, Auth, Data API, Object Storage, Functions) and your branch settings (compute size, TTL, protected). The config commands reconcile that file with what's actually live: neon config plan previews the changes, neon config apply makes them, and neon deploy applies and provisions in one step.

These commands now report their changes as a git diff instead of tables so you can see exactly what will change before you confirm:

If apply finds a setting that already differs on the branch, it shows the current value too and stops without changing anything until you re-run with --update-existing.

New NAT gateway IPs and VPC endpoint services in US East (Ohio), Europe (London), and Asia Pacific (Singapore)

We've expanded infrastructure capacity in the AWS US East (Ohio) (us-east-2), Europe (London) (eu-west-2), and Asia Pacific (Singapore) (ap-southeast-1) regions with new NAT gateway IP addresses and new VPC endpoint service addresses for Private Networking.

UPDATE YOUR IP ALLOWLISTS

If you have IP allowlists on external systems that Neon connects to, update those allowlists to include the new NAT gateway addresses. Connections may be affected intermittently if traffic routes through non-allowlisted NAT gateways.

If you use Private Networking in these regions, you can now use the additional VPC endpoint service addresses for enhanced capacity and reliability. See the Regions documentation for the complete list of NAT gateway IPs and the Private Networking guide for VPC endpoint service addresses by region.

New neon api command in the Neon CLI

The Neon CLI now ships an api command: call any Neon Platform API route from the terminal using your existing CLI login, without hand-building curl requests or giving agents raw API keys.

Dedicated CLI commands cover common workflows, but the Platform API moves faster. With the neon api command, you get full API reach the moment an endpoint exists. Run neon api --list to browse every route from the OpenAPI spec.

Read the announcement for why we built this for agent workflows.

List projects for your organization:

neon orgs list
neon api /projects -Q org_id=org-cool-darkness-12345678

Create a dev branch on an existing project:

neon api /projects/late-frost-12345678/branches -X POST -F branch.name=dev

The -F branch.name=dev flag builds the JSON body { "branch": { "name": "dev" } } automatically. See the api command reference for query parameters, file bodies (-d @file), and output formats.

Cmd+K support for the Neon Console

You can now press Cmd+K (Mac) or Ctrl+K (Windows/Linux) from anywhere in the Neon Console to open a searchable command bar with actions scoped to your current branch and project: navigate to branches, open the SQL editor, create a snapshot, go to settings, and more.

Neon MCP Server: branch expiration on create

The Neon MCP Server create_branch tool now accepts an optional expiresAt parameter (ISO 8601) to set automatic branch deletion when creating a branch, matching the Neon API and console Auto-delete behavior. See branch expiration.

Connect the MCP Server in your editor:

npx add-mcp https://mcp.neon.tech/mcp

For full setup (API key auth, agent skills, and more), run npx neon@latest init. See Connect MCP clients to Neon.

New NAT gateway IPs and VPC endpoint services in US East (Ohio), Europe (London), and Asia Pacific (Singapore)

We've expanded infrastructure capacity in the AWS US East (Ohio) (us-east-2), Europe (London) (eu-west-2), and Asia Pacific (Singapore) (ap-southeast-1) regions with new NAT gateway IP addresses and new VPC endpoint service addresses for Private Networking.

UPDATE YOUR IP ALLOWLISTS

If you have IP allowlists on external systems that Neon connects to, update those allowlists to include the new NAT gateway addresses. Connections may be affected intermittently if traffic routes through non-allowlisted NAT gateways.

If you use Private Networking in these regions, you can now use the additional VPC endpoint service addresses for enhanced capacity and reliability. See the Regions documentation for the complete list of NAT gateway IPs and the Private Networking guide for VPC endpoint service addresses by region.

Postgres turns 30

Postgres turned 30 on July 8. See our post on X.

Neon is a long-term bet on Postgres. We support Postgres 14 through 18 today, with Postgres 19 support on the way. Our team includes Postgres hackers who contribute upstream and support the wider ecosystem through our Open Source Program. We run standard Postgres, not a fork: Neon is Postgres, with serverless branching and autoscaling built around the database millions of developers already rely on.

Happy birthday, Postgres. 🎂🐘

New neon api command in the Neon CLI

The Neon CLI now ships an api command: call any Neon Platform API route from the terminal using your existing CLI login, without hand-building curl requests or giving agents raw API keys.

Dedicated CLI commands cover common workflows, but the Platform API moves faster. With the neon api command, you get full API reach the moment an endpoint exists. Run neon api --list to browse every route from the OpenAPI spec.

Read the announcement for why we built this for agent workflows.

List projects for your organization:

neon orgs list
neon api /projects -Q org_id=org-cool-darkness-12345678

Create a dev branch on an existing project:

neon api /projects/late-frost-12345678/branches -X POST -F branch.name=dev

The -F branch.name=dev flag builds the JSON body { "branch": { "name": "dev" } } automatically. See the api command reference for query parameters, file bodies (-d @file), and output formats.

Cmd+K support for the Neon Console

You can now press Cmd+K (Mac) or Ctrl+K (Windows/Linux) from anywhere in the Neon Console to open a searchable command bar with actions scoped to your current branch and project: navigate to branches, open the SQL editor, create a snapshot, go to settings, and more.

Neon MCP Server: branch expiration on create

The Neon MCP Server create_branch tool now accepts an optional expiresAt parameter (ISO 8601) to set automatic branch deletion when creating a branch, matching the Neon API and console Auto-delete behavior. See branch expiration.

Connect the MCP Server in your editor:

npx add-mcp https://mcp.neon.tech/mcp

For full setup (API key auth, agent skills, and more), run npx neon@latest init. See Connect MCP clients to Neon.

New NAT gateway IPs and VPC endpoint services in US East (Ohio), Europe (London), and Asia Pacific (Singapore)

We've expanded infrastructure capacity in the AWS US East (Ohio) (us-east-2), Europe (London) (eu-west-2), and Asia Pacific (Singapore) (ap-southeast-1) regions with new NAT gateway IP addresses and new VPC endpoint service addresses for Private Networking.

UPDATE YOUR IP ALLOWLISTS

If you have IP allowlists on external systems that Neon connects to, update those allowlists to include the new NAT gateway addresses. Connections may be affected intermittently if traffic routes through non-allowlisted NAT gateways.

If you use Private Networking in these regions, you can now use the additional VPC endpoint service addresses for enhanced capacity and reliability. See the Regions documentation for the complete list of NAT gateway IPs and the Private Networking guide for VPC endpoint service addresses by region.

Postgres turns 30

Postgres turned 30 on July 8. See our post on X.

Neon is a long-term bet on Postgres. We support Postgres 14 through 18 today, with Postgres 19 support on the way. Our team includes Postgres hackers who contribute upstream and support the wider ecosystem through our Open Source Program. We run standard Postgres, not a fork: Neon is Postgres, with serverless branching and autoscaling built around the database millions of developers already rely on.

Happy birthday, Postgres. 🎂🐘

Neon CLI enhancements

We're continually improving the Neon CLI and the developer experience around it. Recent additions include neon link, neon checkout, and neon env pull commands and neon.ts. This week brings a shorter name plus two additional commands.

• The CLI is now just neon

You can now install the Neon CLI from npm as neon instead of neonctl: npm i -g neon (or run it with npx neon@latest). All commands are now documented as neon rather than neonctl. If you already use neonctl, nothing changes: it's the same CLI, neonctl still works as a command, and no migration or re-authentication is needed. See the Neon CLI install guide.

The latest CLI now requires Node.js 20.19.0 or higher (previously 18). An existing installation keeps working on your current Node.js version; if you're on an older version, upgrade Node.js before updating the CLI.

• Set up declarative branch management in one step

The new neon config init command scaffolds a starter neon.ts config file and installs the @neon/config and @neon/env packages, so you can define how each branch is set up (compute size, scale-to-zero, TTL, and which services it uses) declaratively, without any manual setup. It runs entirely locally, and neon link now offers to run it as its final step.

• Check your current branch instantly, with no network call

The new neon status command is a top-level alias for neon config status. Add --current-branch to print just the branch pinned in your local .neon file:

neon status --current-branch

Because it makes no network call, it's fast enough to run on every shell prompt. For example, add your current Neon branch to a starship prompt by appending this [custom.neon] module to ~/.config/starship.toml:

# ~/.config/starship.toml
[custom.neon]
description = "Current Neon branch"
command = "neon status --current-branch" # prints the branch pinned in .neon (no network)
when = "neon status --current-branch" # exits non-zero when no branch -> segment is hidden
symbol = "🌿 "
style = "bold green"
format = "[$symbol$output]($style) "

See the config command reference for more.

Neon Storage in the Files SDK

Neon Storage now has a first-class adapter in the Files SDK, the open-source library that gives you one upload, download, and presigned-URL API across S3, R2, GCS, and more. The neon adapter is wired up from the AWS_* variables Neon injects, so pointing your storage backend at Neon is a one-line config change:

import { Files } from 'files-sdk';
import { neon } from 'files-sdk/neon';
const files = new Files({ adapter: neon({ bucket: 'assets' }) });

// Upload a file, then get a presigned URL to view it
await files.upload('logos/neon-logo.png', body, { contentType: 'image/png' });
const url = await files.url('logos/neon-logo.png', { expiresIn: 3600 });

See the with-files-sdk example for a minimal script that uploads files to a branch-scoped bucket.

Neon Storage is part of Neon's new backend services, currently in private preview. If you haven't signed up yet, you can sign up and learn more.

Learn more about Lakebase Search

We recently opened Lakebase Search to all Neon users, adding scalable vector, keyword, and hybrid search to Postgres through the lakebase_vector and lakebase_text extensions. This week, our engineering team goes under the hood.

Read Lakebase Search: vector and BM25 on Neon blog post to learn why the usual pgvector + GIN setup breaks down at scale, and how lakebase_ann (IVF + RaBitQ) and lakebase_bm25 (Block-Max WAND) keep indexes on object storage so they stay ready across scale-to-zero and branching.

Update snapshot expiration anytime

You can now update a snapshot's expiration with the Update snapshot endpoint. Set expires_at to a future timestamp to change the retention deadline, or send null to remove it so the snapshot never expires. Previously, expiration could only be set when the snapshot was created.

curl --request PATCH \
--url 'https://console.neon.tech/api/v2/projects/{project_id}/snapshots/{snapshot_id}' \
--header 'authorization: Bearer $NEON_API_KEY' \
--header 'content-type: application/json' \
--data '{
  "snapshot": {
    "expires_at": "2026-12-31T00:00:00Z"
  }
}'

Planned update notifications change

So that we can ship Neon improvements and fixes faster, the advance notice period for planned updates on the Scale and Enterprise plans is changing from 7 days to 3 days, effective July 10, 2026. Updates take only a few seconds, and Neon prewarms your cache so performance isn't affected.

You can check for update notifications in your project's settings (Settings > Updates). On the Scale and Enterprise plans, you also receive an email notification in advance, in addition to the in-console notice. To learn more, see Updates.

Neon Community Corner

This week, we're spotlighting contributions and integrations from the Neon community and ecosystem.

Neon Testing now supports Bun Test

Neon Testing, the community-built integration testing library by Mikael Lirbank, shipped v3.0.0 with support for Bun Test alongside Vitest. Each test runs against its own isolated Neon branch, with DATABASE_URL set up and torn down automatically, so your tests hit the same schema and constraints as production without mocks or a shared local database.

npm install --save-dev neon-testing

View the package on npm and read the v3.0.0 release notes on GitHub.

Connect Neon to Gamut

Gamut, an AI agent hosting platform with native support for remote MCP servers, now connects to Neon through the Neon MCP server. Setup uses OAuth, matching the existing client flow. To get started, add Neon to your Gamut agent.

Docs & Postgres tutorial contributors

Our docs and Postgres tutorials get better thanks to fixes and improvements from the community. A quick thank you to contributors.

@AayushGoswami @AhmedYasinKUL @Arul-1911 @bcw117 @camro @chibx @codenim34 @crebelskydico @da-vaibhav @DorianDragaj @duffuniverse @fcdm @flow145 @harry-whorlow @houssaineamzil @ifeoluwak @Jaskaranrehal @jayhyp @karlhorky @keugenek @michaelgomeh @noo-dev @rahulrao0209 @Ranzeplay @realihorrud @rhutch117 @sanaeft @sdarnadeem @SefterM-zade @slotix @solisoares @this-fifo @VIM4L-M @webwurst

Neon CLI enhancements

We're continually improving the Neon CLI and the developer experience around it. Recent additions include branch-first dev loop (neon link, neon checkout, and neon env pull) commands and neon.ts. This week brings a shorter name plus two additional commands.

• The CLI is now just neon

You can now install the Neon CLI from npm as neon instead of neonctl: npm i -g neon (or run it with npx neon@latest). All commands are now documented as neon rather than neonctl. If you already use neonctl, nothing changes: it's the same CLI, neonctl still works as a command, and no migration or re-authentication is needed. See the Neon CLI install guide.

The latest CLI now requires Node.js 20.19.0 or higher (previously 18). An existing installation keeps working on your current Node.js version; if you're on an older version, upgrade Node.js before updating the CLI.

• Set up declarative branch management in one step

The new neon config init command scaffolds a starter neon.ts config file and installs the @neon/config and @neon/env packages, so you can define how each branch is set up (compute size, scale-to-zero, TTL, and which services it uses) declaratively, without any manual setup. It runs entirely locally, and neon link now offers to run it as its final step.

• Check your current branch instantly, with no network call

The new neon status command is a top-level alias for neon config status. Add --current-branch to print just the branch pinned in your local .neon file:

neon status --current-branch

Because it makes no network call, it's fast enough to run on every shell prompt. For example, add your current Neon branch to a starship prompt by appending this [custom.neon] module to ~/.config/starship.toml.

See the config command reference for more.

Neon Object Storage in the Files SDK

Neon Object Storage now has a first-class adapter in the Files SDK, the open-source library that gives you one upload, download, and presigned-URL API across S3, R2, GCS, and more. The neon adapter is wired up from the AWS_* variables Neon injects, so pointing your object storage backend at Neon is a one-line config change.

See the with-files-sdk example for a minimal script that uploads files to a branch-scoped bucket.

Neon Object Storage is part of Neon's new backend services, currently in private preview. If you haven't signed up yet, you can sign up and learn more.

Learn more about Lakebase Search

We recently opened Lakebase Search to all Neon users, adding scalable vector, keyword, and hybrid search to Postgres through the lakebase_vector and lakebase_text extensions. This week, our engineering team goes under the hood.

Read Lakebase Search: vector and BM25 on Neon blog post to learn why the usual pgvector + GIN setup breaks down at scale, and how lakebase_ann (IVF + RaBitQ) and lakebase_bm25 (Block-Max WAND) keep indexes on object storage so they stay ready across scale-to-zero and branching.

Update snapshot expiration anytime

You can now update a snapshot's expiration with the Update snapshot endpoint. Set expires_at to a future timestamp to change the retention deadline, or send null to remove it so the snapshot never expires. Previously, expiration could only be set when the snapshot was created.

Planned update notifications change

So that we can ship Neon improvements and fixes faster, the advance notice period for planned updates on the Scale and Enterprise plans is changing from 7 days to 3 days, effective July 10, 2026. Updates take only a few seconds, and Neon prewarms your cache so performance isn't affected.

You can check for update notifications in your project's settings (Settings > Updates). On the Scale and Enterprise plans, you also receive an email notification in advance, in addition to the in-console notice. To learn more, see Updates.

Neon Community Corner

This week, we're spotlighting contributions and integrations from the Neon community and ecosystem.

Neon Testing now supports Bun Test

Neon Testing, the community-built integration testing library by Mikael Lirbank, shipped v3.0.0 with support for Bun Test alongside Vitest. Each test runs against its own isolated Neon branch, with DATABASE_URL set up and torn down automatically, so your tests hit the same schema and constraints as production without mocks or a shared local database.

Connect Neon to Gamut

Gamut, an AI agent hosting platform with native support for remote MCP servers, now connects to Neon through the Neon MCP server. Setup uses OAuth, matching the existing client flow. To get started, add Neon to your Gamut agent.

Docs & Postgres tutorial contributors

Our docs and Postgres tutorials get better thanks to fixes and improvements from the community. A quick thank you to contributors.

The link command

The link command binds the current directory to a Neon project. It picks (or creates) an organization and project, resolves the project's default branch, and writes a .neon file with orgId, projectId, and branchId. Subsequent commands run in this directory (or any subdirectory) automatically pick up that context.

Requires neonctl 2.22.2 or later. Check your version with neonctl --version.

PREFER LINK OVER SET-CONTEXT

For most workflows, use neonctl link instead of manually running neonctl set-context --project-id .... The link command guides you through organization and project selection and ensures the context file is complete.

Usage

neonctl link [options]

Options

• --org-id: Organization ID to link to (string, not required)
• --project-id: Existing project ID to link to (string, not required)
• --project-name: Name for a new project to create and link to (string, not required)
• --region-id: Region ID for a new project (e.g. aws-us-east-2). Required with --project-name. (string, not required)
• --branch, --branch-id: Branch name or ID to pin in the context (resolved to its ID before writing). Without it, link only resolves the org and project — pin a branch with neonctl checkout (link never guesses a default). (string, not required)
• --params: JSON object with link parameters, e.g. '{"orgId":"...","projectId":"..."}' or '{"orgId":"...","projectName":"...","regionId":"..."}'. Flags take precedence over fields in --params. (string, not required)
• --agent: Emit a JSON state-machine response designed for AI agents instead of prompting. The output is a single JSON object with a discriminated status field describing the next step. (boolean, default false, not required)
• --yes, -y: Skip the "already linked" confirmation in interactive mode and re-link anyway. (boolean, default false, not required)
• --clear: Remove the org/project/branch context (writes an empty context file) instead of linking. (boolean, default false, not required)
• --checks: Verify the org/project/branch exist (and resolve the org from the project) before writing. On by default; use --no-checks to write the context offline with no API calls — it then requires --org-id and --project-id (--branch optional) and skips env pull. (boolean, default true, not required)
• --env-pull: Pull the linked branch's Neon env vars (DATABASE_URL, ...) into a local .env after linking. On by default; use --no-env-pull to skip, for example when injecting env at runtime with neon-env run (from @neondatabase/env) or neonctl dev. (boolean, default true, not required)

By default, linking pulls the linked branch's environment variables (such as DATABASE_URL) into a local .env file. Use --no-env-pull to skip this step, for example when you inject environment variables at runtime instead.

Interactive mode (default)

Run neonctl link with no flags for guided prompts:

Output example:

? Which organization would you like to link? › Personal Org (org-abc123)
? Which project would you like to link? › + Create new project
? Name for the new project: › my-app
? Which region should the new project run in? › AWS US East (Ohio) (aws-us-east-2)
Created project polished-snowflake-12345678 ("my-app") in aws-us-east-2.
Linked .neon:
orgId:     org-abc123
projectId: polished-snowflake-12345678
branchId:  br-steep-math-aiu3vve7

Non-interactive mode

Use flags or a --params JSON blob for scripts and CI:

# Link to an existing project
neonctl link --org-id org-abc123 --project-id polished-snowflake-12345678

# Create a new project and link
neonctl link --org-id org-abc123 --project-name my-app --region-id aws-us-east-2

# Same payload, one JSON blob
neonctl link --params '{"orgId":"org-abc123","projectName":"my-app","regionId":"aws-us-east-2"}'

Flags take precedence over fields in --params.

Agent mode

Use --agent for a JSON state machine designed for AI coding assistants. Each invocation returns a single JSON object with a status discriminator describing the next step, the available options, and the exact follow-up command to run.

Example response when an organization must be selected:

{
  "status": "needs_org",
  "instruction": "Ask the user which of these 2 organizations they want to link the current directory to. After they pick one, re-run the next_command_template with the chosen --org-id value.",
  "options": [
    {"id": "org-abc123", "name": "Personal Org"},
    {"id": "org-team", "name": "Team Org"}
  ],
  "next_command_template": "neonctl link --agent --org-id <org_id>"
}

When linking completes, the response includes status: "linked" with the context file path and project details.

Any unexpected failure in --agent mode is reported as JSON to stdout with exit code 1:

{
  "status": "error",
  "code": "CLIENT_ERROR",
  "message": "user has no access to projects"
}

The .neon context file

The link command is a thin wrapper around set-context: both write to the same .neon file, so anything link can write, set-context can write too.

link writes the file into the current working directory by default. If an existing .neon is found in any parent directory, that file is reused, so commands run from a subdirectory of a linked project still pick up the project's context. To pin the location explicitly, pass the global --context-file option.

Example .neon file:

{
  "orgId": "org-abc123",
  "projectId": "polished-snowflake-12345678",
  "branchId": "br-steep-math-aiu3vve7"
}

The first time a .neon file is created, the CLI adds .neon to .gitignore in that folder so local project settings are not committed by accident. If you want to commit .neon and share context with your team, remove the entry from .gitignore. The CLI doesn't re-add it when updating an existing file.

NOTE

Neon does not save confidential information to the context file (for example, auth tokens). You can safely commit this file to your repository or share it with others.

Organization-scoped API keys

Organization-scoped API keys (those created at the organization level rather than the user level) cannot list user organizations or call the regions endpoint. link handles this transparently:

• If the API key is org-scoped and at least one project already exists in the org, the CLI auto-detects the org_id from the first project.
• If the API key is org-scoped and no projects exist yet, --agent returns a needs_org response with options: [] and an instruction to find the org ID in the Neon Console. Interactive mode prints an error pointing to --org-id.
• When the regions endpoint is not allowed, link falls back to a built-in static region list.

Pin a branch in your local .neon context file

The checkout command pins a branch in the local context so subsequent commands target it. It's a focused helper over set-context for the common "switch the branch I'm working on" case. The checkout command requires neonctl 2.22.2 or later; check your version with neonctl --version.

checkout resolves the branch (by name or ID) against the project, then heals the .neon file: it always (re)writes projectId, branchId, and orgId (when the project has one), so a .neon that was missing fields or drifted ends up complete and consistent.

Usage

neonctl checkout [id | name] [options]

The branch argument is optional. Run neonctl checkout with no branch in an interactive terminal to fetch the project's branches and pick one from a list. In a non-interactive context (CI or no TTY), you must pass a branch explicitly.

Options

• --project-id: Project ID (string, not required)
• --env-pull: Pull the branch's Neon env vars (DATABASE_URL, ...) into a local .env after checkout. On by default; use --no-env-pull to skip, for example when injecting env at runtime with neon-env run (from @neondatabase/env) or neonctl dev. (boolean, default true, not required)

By default, checkout pulls environment variables into a .env file after checking out the branch; use --no-env-pull to skip this.

Branch ID vs name

Branch ID vs name is detected automatically (a br-… value is treated as an ID):

• ID: Matched strictly by ID. A non-existent ID is a hard "not found" error (IDs are server-assigned, so checkout never creates one).
• Name: Matched by name. If the name does not exist, in an interactive terminal checkout offers to create it (equivalent to neonctl branches create --name : branched from the project's default branch with a read-write compute), then checks it out. In a non-interactive context, a missing name is the usual "not found" error.

Project resolution

The project is resolved through the standard Neon CLI chain, each entry winning over the next:

1. --project-id flag
2. projectId from the closest .neon file (found by walking up from the current directory)
3. If still unresolved and the API key maps to exactly one project, that project is auto-detected (same behavior as branches and connection-string)

If none of those resolve a project, checkout prints an error explaining the chain above. In an interactive terminal it then offers to run neonctl link in the current folder so you can pick (or create) a project on the spot. In non-interactive contexts, it exits with a non-zero code instead of prompting.

Examples

Pin a branch by name. New Neon projects create a default branch named production:

neonctl checkout production --project-id polished-snowflake-12345678

Output:

INFO: Checked out branch br-steep-math-aiu3vve7 on project polished-snowflake-12345678. Updated /path/to/cwd/.neon.

The updated .neon file:

{
  "orgId": "org-abc123",
  "projectId": "polished-snowflake-12345678",
  "branchId": "br-steep-math-aiu3vve7"
}

Pick a branch interactively (requires a linked project or --project-id):

neonctl checkout

Pin a branch by ID:

neonctl checkout br-cool-snow-12345678 --project-id polished-snowflake-12345678

After checking out a branch, commands such as connection-string and psql use the pinned branch by default.