neonctl

library2.22.0jsnpmunverified

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.

devops database

npm install neonctl

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NEONCTL

neonctl

devopsjavascriptv2.22.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

npx neonctl

✓ npx neonctl

✗ npm install neonctl && neonctl

npx executes the CLI directly; global install optional.

npm i -g neonctl

✓ npm i -g neonctl

✗ npm install neonctl (missing -g)

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.

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

neonctl --version

Debug

Known issues

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

fix

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

affects: >=2.19.0

breakingNode.js 18 is required. Lower versions will fail to run (engine requirement).

fix

Upgrade Node.js to v18 or higher.

affects: >=2.0.0

gotchaCommands 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.

affects: 2.19.1

gotchaWhen 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.

affects: >=1.0.0

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

affects: >=2.18.0

Errors

Common errors & fixes

neonctl: command not found

The package is not installed globally or not in PATH.

fix

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

Error: org_id is required

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: API key not valid. Pass it via --api-key

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: Connection timeout. The Neon API is not reachable.

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.

Upgrade

Version history

2.22.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

35 hits · last 30 days

node

Resources

githubhttps://github.com/neondatabase/neonctl ↗

packagehttps://www.npmjs.com/package/neonctl ↗

homepagehttps://neon.tech ↗