Neon CLI

One CLI for every Neon surface: manage Postgres, Functions, Storage, the Data API, and Managed Better Auth from the terminal, with branch-scoped workflows built in.

Install

npm i -g neon

Get started

Install and connect
Install the Neon CLI, authenticate, and connect your first Neon project in minutes.
Quickstart
Create a project, manage branches, and run your first Neon CLI commands.

Agent mode

Use Neon CLI with Claude Code, Cursor, Codex, and other AI development tools.

note

Every command supports --output json for machine-readable results, and setting the NEON_API_KEY environment variable authenticates non-interactively. For AI agents, neon link --agent emits a JSON state-machine response with a discriminated status field describing the next step, instead of prompting.

Commands reference

Browse every Neon CLI command, organized by category. The CLI is invoked as neon. neonctl is an alias for neon, so any command works with either name.

Setup & context

Command	Description	Example
auth	Browser OAuth; stores credentials locally.	`neon auth`
bootstrap	Scaffold a new project from a Neon starter template	`neon bootstrap my-appneon bootstrap . --template hononeon bootstrap my-app --default`
checkout	Pin a branch in .neon; auto-pulls its env vars.	`neon checkout feat/auth`
env	Write the branch's DATABASE_URL + Neon vars to .env.	`neon env pull`
init	Wire up MCP, agent skills, and editor (Cursor/VS Code/Claude).	`npx neon@latest init`
link	Bind the directory to a project; writes .neon and pulls env.	`neon linkneon link --org-id org-abc --project-id polished-snowflake-1234`
me	Show the authenticated user.	`neon me`
set-context	Write org/project/branch context to .neon.	`neon set-context --project-id polished-snowflake-1234`

Projects & branches

Command	Description	Example
branches	Create, diff, reset, restore, and manage branches.	`neon branches create --name feat/auth --parent mainneon branches restore main ^self@2024-05-06T10:00:00Z --preserve-under-name backupneon branches schema-diff production development`
databases	Manage databases on a branch.	`neon databases create --name analytics`
diff	Show a git-style schema diff between the current branch and another branch	`neon diff main --db neondbneon diff main --branch feature/checkoutneon diff`
operations	Inspect async operations.	`neon operations list`
projects	Manage projects.	`neon projects list`
roles	Manage Postgres roles.	`neon roles create --name app_user`
snapshots	Manage snapshots	`neon snapshots create --branch main --lsn 0/1F3C8A0 --expires-at 2025-12-31T23:59:59Zneon snapshots create --branch main --timestamp 2025-01-01T00:00:00Zneon snapshots create --branch main --name pre-migration`

Connect to Postgres

Command	Description	Example
connection-string	Print a connection URI for a branch/role/db.	`neon connection-string mainneon connection-string main --pooled --prisma`
psql	Open a SQL session (embedded psql fallback built in).	`neon psql main -- -c "SELECT 1"`

Config as code

Command	Description	Example
config	Drive a branch from a neon.ts policy.	`neon config apply`
deploy	Alias for config apply; reconciles the policy.	`neon deploy`
dev	Run Neon Functions locally with hot reload + branch env.	`neon dev`
status	Show the branch's live Neon state (alias of config status).	`neon status`

Functions, storage & data

Command	Description	Example
buckets	Branch-scoped object storage and its objects.	`neon buckets create my-assets`
data-api	Manage the Neon Data API for a database.	`neon data-api create`
functions	Deploy and manage Neon Functions on a branch.	`neon functions deploy api --src ./api.ts`
neon-auth	Manage Neon Auth on a branch.	`neon neon-auth enable`

Org & network

Command	Description	Example
api	Call any Neon API route directly (authenticated passthrough)	`neon api /projectsneon api /projects/{id}/branches -X POST -F branch.name=devneon api --list`
ip-allow	Manage the project IP allowlist.	`neon ip-allow add 203.0.113.0/24`
orgs	List organizations you belong to.	`neon orgs list`
vpc	Manage VPC endpoints and project restrictions.	`neon vpc endpoint list`

Debugging

Command	Description	Example
inspect	Inspect a database's health and configuration	`neon inspect <sub-command> [options]`

Global options

Global options are optional and work with any Neon CLI command.

Option	Description	Type	Default	Required
`--analytics`	Manage analytics. Example: --no-analytics, --analytics false	boolean	`true`	No
`--api-key`	Neon API key, authenticates without `neon auth`	string	NEON_API_KEY environment variable	No
`--color`	Colorize the output. Example: --no-color, --color false	boolean	`true`	No
`--config-dir`	Path to config directory	string	~/.config/neonctl (or $XDG_CONFIG_HOME/neonctl)	No
`--context-file`	Context file with default org, project, and branch IDs, created by `neon link`	string	nearest .neon file, searching upward from the current directory	No
`--help`, `-h`	Show help for a command or subcommand	boolean	—	No
`--output`, `-o`	Set output format Possible values: `json`, `yaml`, `table`	string	`table`	No
`--version`, `-v`	Show version number	boolean	—	No

More about global options:

Output: table output may omit fields. Use --output json or --output yaml to see all data.
Authentication: the CLI checks credentials in this order: the --api-key option, the NEON_API_KEY environment variable (export NEON_API_KEY=<neon_api_key>), the credentials.json file that neon auth creates in the config directory (override its location with --config-dir), then interactive web authentication. To get a key, see Create an API key.
Context file: sets a default organization, project, or branch so you don't repeat IDs in every command. Create one with neon link (preferred) or set-context.
Analytics: Neon collects anonymous data about which commands and options are used, never user-defined data such as project IDs or command payloads. Opt out with --no-analytics.
Help: --help works at every level: neon --help, neon branches --help, neon branches create --help.

GitHub repository

The Neon CLI is open source. See the neondatabase/neon-pkgs repository.