Install

The CLI is invoked as neon, and neonctl is an alias for neon. The Homebrew formula is named neonctl, so install commands use that name even though you run the CLI as neon.

Install with Homebrew

brew install neonctl

Install via npm

npm i -g neon

Requires Node.js 20.19.0 or higher.

Install with bun

bun install -g neon

macOS binary

Download the binary. No installation required.

curl -sL https://github.com/neondatabase/neon-pkgs/releases/latest/download/neonctl-macos-x64 -o neon

Run the CLI from the download directory:

neon <command> [options]

Use the Neon CLI without installing

You can run the Neon CLI without installing it using npx or the bun equivalent, bunx:

# npx
npx neon <command>

# bunx
bunx neon <command>

Upgrade

Upgrade using the method that matches how you installed the CLI. To check for the latest version, see the Neon CLI Releases page. To check your installed version, run:

neon --version

Node.js 20.19.0 is required to upgrade

The current CLI requires Node.js 20.19.0 or higher. An existing installation keeps working on your current Node.js version, but upgrading to the latest CLI on an older version (such as Node.js 18) fails. If you're on an older version, upgrade Node.js before you upgrade the CLI.

npm update -g neon

In CI/CD tools like GitHub Actions, you can safely pin the Neon CLI to latest, as we prioritize stability for CI/CD processes.

In your GitHub Actions workflow, use the latest tag with npm:

- name: Install Neon CLI
  run: npm install -g neon@latest

Connect

The Neon CLI supports connecting via web authentication or API key.

Web authentication

Run the following command to connect to Neon via web authentication:

neon auth

The neon auth command launches a browser window where you can authorize the Neon CLI to access your Neon account. If you haven't authenticated previously, running any Neon CLI command launches the web authentication process automatically unless you've specified an API key.

note

If you use Neon through the Vercel-Managed Integration, you must authenticate connections from the CLI client using a Neon API key (see below). The neon auth command requires an account registered through Neon rather than Vercel.

API key

To authenticate with a Neon API key, specify the --api-key option when running a Neon CLI command:

neon projects list --api-key <neon_api_key>

To avoid including --api-key with each command, export your API key to the NEON_API_KEY environment variable.

export NEON_API_KEY=<neon_api_key>

For information about obtaining a Neon API key, see Creating API keys.

Configure autocompletion

The Neon CLI supports autocompletion. See Neon CLI commands: completion to set it up.