CLI · Databases and backend · Neon
Neon CLI
Manage Neon Postgres projects, branches, roles and connections from a terminal, with JSON output for scripts and agents.
Deletes are real. Project and branch deletions remove data. Script them with explicit IDs and review before running.
Understand the tool
What it does.
The Neon CLI (the neon command, also installed as neonctl for compatibility) manages Neon projects, branches, databases, roles, snapshots and functions, and opens psql connections. Every command supports JSON output, and the NEON_API_KEY environment variable authenticates non-interactively.
Why use it?
Use it to create a branch for a test, compare schemas between branches or get a connection string in a script. Branching makes it easy to try changes away from your main data.
A useful fit for
- Per-feature database branches
- Schema diffs between branches
- Scripted project setup in CI
From need to output
Ways to put it to work.
These are suggested workflows based on the documented capabilities. They are not recorded runtime results.
Use case 01
Create a branch for a pull request
A developer wants a database copy for testing a change.
- Create a branch from main.
- Get its connection string.
- Delete it after the change merges.
Intended outputAn isolated database copy per change.
Use case 02
Review a schema change
A reviewer wants to see what a migration changed.
- Run neon diff against the main branch.
- Read the git-style diff.
- Approve or request changes.
Intended outputA readable schema diff before merging.
A concrete starting point
Show the installed version
Prints the CLI version without contacting Neon. Add --output json to other commands for machine-readable results.
neon --versionWhat this can change
None; does not contact Neon or read credentials.
This example has not been executed for this review. Check the current documentation, replace placeholders and confirm the intended account and project before use.
Before you start
Setup and access.
What you’ll need
- Node.js for npm i -g neon
- A Neon account; browser login or a NEON_API_KEY for non-interactive use
- psql for neon psql
- Authentication
- Browser login, or an API key through --api-key or NEON_API_KEY; named credential profiles are supported.
- Can read
- Projects, branches, databases, roles and operations the account can access
- Can write or change
- Project, branch, role, snapshot and function changes, including deletions, when commands allow
- Network and data flow
- Neon API
- Neon analytics unless disabled with --no-analytics
- Approval and control
- The CLI acts with the key's or login's full rights. Commands like neon mcp and neon skills write agent configuration files; review what they write.
Check your environment
Compatibility, costs and license.
Compatibility notes
- Any platform with Node.js
- neon and neonctl commands from the same release
- JSON, YAML or table output
Costs and account requirements
The CLI is free. Neon plan limits and compute usage apply to the projects it manages.
Current pricing or plan information ↗Apache-2.0
Code license; Neon service use is governed by Neon's platform terms.
Read the license or service terms ↗Keep the boundaries visible
Concerns and limitations.
Deletes are real
Project and branch deletions remove data. Script them with explicit IDs and review before running.
API keys are broad
An API key can manage every project it reaches. Prefer scoped keys and named profiles.
Where it may fall short
- Only version and help ran, without credentials.
- The repository named by the package is neondatabase/neon-pkgs; the older neonctl repository is archived.
Observed behavior · 2026-10-18
Runtime and security findings.
The official neon package reported version 8.8.0 and printed its command and option help without credentials. No Neon API call was made.
These checks cover the conditions below. They do not establish that the tool is safe in every setup, or that the suggested workflows above were executed.
What we found
Observed in this evaluation · low severity under stated conditions
Analytics are on by default
The help output shows --analytics defaults to true.
In practice: Pass --no-analytics, or set it in CI, if you do not want usage analytics sent.
Observed in this evaluation
Some commands write agent configuration
The help lists mcp, skills and plugins commands that install Neon tooling into coding agents.
In practice: Review the files these commands write before running them on a shared machine.
Version, environment and fixture
- Version or deployment
- neon 8.8.0 (npm latest at test time)
- Tested target
- neon from the npm registry, run as neon
- Artifact identity
- npm dist.integrity sha512-P7b7TGm/WfyOy3p85EvK0IQHOZYMSiEJrbslo3leEjtnRiuvsysUZWfuOt3W+38ZoLuogJ67QmFBcBAsjIrJdg== (registry-published package integrity; not an independent provenance audit)
- Environment and fixture
- Debian Linux x86_64 (kernel 6.12); Node.js 24.18.0; npm 11.16.0; installed with --ignore-scripts into an isolated directory.
- Fresh HOME; environment limited to PATH plus NEON_DISABLE_ANALYTICS and CI; no NEON_API_KEY, profile or login.
- Observed 2026-10-19T06:29:40.903323+00:00 through 2026-10-19T06:29:41.290495+00:00 UTC.
Checks and results
2 recorded checks. Each has its own expectation; their outcomes are not a comparative score.
Installed versionMet expectation
- Method
neon --version- Expected
- Print the package version.
- Observed
- Exit 0. 8.8.0
Command and option helpMet expectation
- Method
neon --help- Expected
- List commands and global options without needing credentials.
- Observed
- Exit 0. Listed command groups including projects, databases, roles, snapshots, functions, psql, diff, mcp and skills (the saved transcript keeps the last 4,000 characters of the help text); global options include --output (json, yaml, table), --profile, --api-key (default NEON_API_KEY) and --analytics (default true).
Practical caveats
- neonctl is a compatibility package for the same CLI; the documented install is npm i -g neon.
- Installed with --ignore-scripts.
What this evaluation does not establish
- Login, API-key use, project and branch operations, psql connections and schema diffs.
- The neon mcp, skills and plugins installers, which write agent configuration; analytics behavior with defaults on.
Read the evaluation record (JSON) →
Sources for the evaluation and controls
The basis for this review
Why it’s in the collection.
A capable first-party CLI with JSON output and branch-based workflows. Ranked after the Salesforce CLI because fewer small businesses run their own Postgres.
The number is an editorial starting order within the cli tools collection. It does not measure popularity, speed, reliability or safety.
Why we added it
Round-6 directory addition: first-party CLI paired with the Neon MCP Server entry.
Selection evidence checked .
- Repository interest
- 63 GitHub stars at this snapshot ↗
Repository-level interest for the monorepo that publishes the neon package
- Repository activity
- Last push reported by GitHub: . A push can include documentation or maintenance; it does not establish a new stable release.
- Release signal
- neon@8.8.0 ↗ · published . This selection signal can differ from the exact runtime tested above.
- Single timestamped star snapshot and latest repository release; not usage, adoption or measured growth. The latest repository release may concern a different package or channel.
- Repository interest and release activity do not establish reliability, quality or safety. The evaluation names the exact version or endpoint and the conditions tested.
What we reviewed
- Official CLI documentation
- Local credential-free run
The evaluation above lists the current runtime coverage and untested behavior.
Reviewed Oct 18, 2026. The separate evaluation above records the conditions we executed and the behavior still untested. Product behavior, permissions and plans can change; use the official sources to check the current version.
Follow the evidence
Official sources.
- Official Neon CLI documentation ↗neon.com
- Official CLI command reference ↗neon.com
- Official package repository and license ↗github.com
- Neon platform terms ↗neon.com