This section describes how to install the Neon CLI and connect via web authentication or API key.

Install with Homebrew

brew install neonctl

Install via npm

npm i -g neonctl

Requires Node.js 18.0 or higher.

Install with bun

bun install -g neonctl

macOS binary

Download the binary. No installation required.

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

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 (Node Package eXecute) or the bun equivalent, bunx. For example:

# npx
npx neonctl <command>

# bunx
bunx neonctl <command>

Upgrade

When a new version is released, you can update your Neon CLI using the methods described below, depending on how you installed the CLI initially. To check for the latest version, refer to the Releases information on the Neon CLI GitHub repository page. To check your installed version of the Neon CLI, run the following command:

neon --version

To upgrade the Neon CLI via npm:

npm update -g neonctl

If you're using the Neon CLI 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, you can use the latest tag with npm:

- name: Install Neon CLI
  run: npm install -g neonctl@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 have not authenticated previously, running a Neon CLI command automatically launches the web authentication process unless you have 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, you can specify the --api-key option when running a Neon CLI command. For example, the following neon projects list command authenticates to Neon using the --api-key option:

neon projects list --api-key <neon_api_key>

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

export NEON_API_KEY=<neon_api_key>

For information about obtaining an Neon API key, see Create an API key.

Configure autocompletion

The Neon CLI supports autocompletion, which you can configure in a few easy steps. See Neon CLI commands — completion for instructions.