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. Get started. Install and connect Qui...

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.

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
api-keys	Manage API keys	`neon api-keys <sub-command> [options]`
ask	Ask the Neon assistant a question from the terminal.	`neon ask --prompt "How do schema-only branches work?"`
bootstrap	Scaffold a new project from a Neon starter template, then install agent tooling and link a Neon project	neon bootstrap my-app``neon bootstrap . --template hono``neon bootstrap my-app --default
checkout	Pin a branch in .neon; auto-pulls its env vars.	`neon checkout feat/auth`
claim	Create and claim a temporary project without an account.	neon claim create --env-pull``neon claim accept
env	Write the branch's DATABASE_URL + Neon vars to .env.	`neon env pull`
git	Sync the checked-out Neon branch to your git branch on checkout (Preview).	neon git install``neon git status
init	Set up this directory for Neon: agent tooling, a linked project, and optionally neon.ts.	`npx neon@latest init`
link	Bind the directory to a project; writes .neon and pulls env.	neon link``neon link --org-id org-abc --project-id polished-snowflake-1234
mcp	Install the Neon MCP server into your coding agents.	neon mcp``neon mcp -y
me	Show the authenticated user.	`neon me`
open	Open the linked project in the Neon Console in your browser.	`neon open`
plugins	Install the Neon plugin (skills plus MCP) into your coding agents.	neon plugins``neon plugins -y``neon plugins --global
profile	Manage named sets of Neon credentials	neon profile create work``neon profile create ci --mint --org-id org-abc-123
set-context	Write org/project/branch context to .neon.	`neon set-context --project-id polished-snowflake-1234`
skills	Install and update Neon agent skills in your coding agents.	neon skills``neon skills -y``neon skills update -y
login	Browser OAuth; stores credentials locally.	`neon login`

Projects & branches

Command	Description	Example
branches	Create, diff, reset, restore, and manage branches.	neon branches create --name feat/auth --parent main``neon branches restore main ^self@2024-05-06T10:00:00Z --preserve-under-name backup``neon 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 neondb``neon diff main --branch feature/checkout``neon 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:59Z``neon snapshots create --branch main --timestamp 2025-01-01T00:00:00Z``neon snapshots create --branch main --name "Before migration" --slug before-migration

Connect to Postgres

Command	Description	Example
connection-string	Print a connection URI for a branch/role/db.	neon connection-string main``neon 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`
credentials	Issue and manage scoped credentials on a branch.	`neon credentials create --scope storage:read`
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`
triggers	Invoke a Neon Function on a cron schedule or when an object is created.	`neon triggers create --function-slug api --name nightly --cron '0 6 * * *'`

Org & network

Command	Description	Example
api	Call any Neon API route directly (authenticated passthrough)	neon api /projects``neon api /projects/{id}/branches -X POST -F branch.name=dev``neon 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 branch's Postgres health and configuration	`neon inspect <sub-command> [options]`
logs	Query branch logs	neon logs field-values service_name --since 6h``neon logs query --since 1h --logql '{entity_type="function"} \|= "timeout"'``neon logs query --branch main --source pg_endpoint --minimum-severity error

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 login`	string	`""`	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
`--profile`	Named credentials to use, from profiles.json (default: NEON_PROFILE, else DEFAULT)	string	—	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 login 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.