Neon CLI

2.22.0 verified Sat Apr 25 auth: no javascript

Official command-line tool for managing Neon Serverless Postgres databases. Version 2.22.0, released March 2026. Requires Node.js >=18. Provides project, branch, database, role, and IP allow management, plus connection string retrieval. Supports authentication via browser OAuth or API key. Installable via npm, Homebrew, or binary downloads. Not to be confused with neon.js SDK — this is a CLI binary, not a library for programmatic use.

Common errors

error neonctl: command not found ↓

cause The package is not installed globally or not in PATH.

fix

Run 'npm i -g neonctl' or use 'npx neonctl' instead.

error Error: org_id is required ↓

cause Missing or incorrect organization context when running project-scoped commands.

fix

Upgrade to v2.20.0 or later, or provide the correct --org-slug.

error Error: API key not valid. Pass it via --api-key ↓

cause No authentication token found; either run 'neonctl auth' or provide a valid API key with --api-key.

fix

Run 'neonctl auth' to log in with browser, or pass your API key: 'neonctl projects list --api-key <key>'.

error Error: Connection timeout. The Neon API is not reachable. ↓

cause Network issue or API outage; check your internet connection and status.neon.tech.

fix

Retry after checking network connectivity. If issue persists, contact Neon support.

Warnings

deprecated The --org-id flag is deprecated in favor of --org-slug for organization-scoped commands. ↓

fix Use --org-slug <slug> instead of --org-id <id>.

breaking Node.js 18 is required. Lower versions will fail to run (engine requirement). ↓

fix Upgrade Node.js to v18 or higher.

gotcha Commands that require a project ID will fail with 'org_id is required' if organization context is wrong. This was a bug in v2.19.1 fixed in v2.20.0. ↓

fix Upgrade to v2.20.0 or later, or ensure you are using the correct org slug.

gotcha When using --api-key, it is visible in process listing; avoid in shared environments. ↓

fix Use neonctl auth with browser OAuth for shared machines, or securely pass via environment variable.

deprecated The --branch flag for 'connection-string' command may be removed; use --branch-name or --branch-id explicitly.

Install

npm install neonctl

yarn add neonctl

pnpm add neonctl

Imports

npx neonctl
wrong
```
npm install neonctl && neonctl
```
correct
```
npx neonctl
```
npx executes the CLI directly; global install optional.
npm i -g neonctl
wrong
```
npm install neonctl (missing -g)
```
correct
```
npm i -g neonctl
```
Global install recommended for regular use; local install in project works but CLI won't be in PATH.
brew install neonctl
```
brew install neonctl
```
Homebrew installation; upgrade with brew upgrade neonctl.

Quickstart

Shows authentication (browser or API key), project creation, branch listing, and connection string retrieval.

# Authenticate (opens browser)
neonctl auth

# Or with API key
neonctl projects list --api-key $(process.env.NEON_API_KEY ?? '')

# Create a project
neonctl projects create --name my-project --region-id us-east-2 --pg-version 16

# List branches
neonctl branches list

# Get connection string
neonctl connection-string