The Neon CLI is a command-line interface that lets you manage Neon directly from the terminal. This documentation references all commands and options available in the Neon CLI.

🚀 Get set up in just a few steps with the CLI Quickstart.

Install

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]

For more about installing, upgrading, and connecting, see Neon CLI — Install and connect.

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>

Synopsis

neon --help usage: neon <command> [options] [aliases: neonctl]  Commands:  neon auth Authenticate [aliases: login]  neon me Show current user  neon orgs Manage organizations [aliases: org]  neon projects Manage projects [aliases: project]  neon ip-allow Manage IP Allow  neonctl vpc Manage VPC endpoints and project VPC restrictions  neon branches Manage branches [aliases: branch]  neon databases Manage databases [aliases: database, db]  neon roles Manage roles [aliases: role]  neon operations Manage operations [aliases: operation]  neon connection-string [branch] Get connection string [aliases: cs]  neon set-context Set the current context  neon completion generate completion script  Global options:  -o, --output Set output format  [string] [choices: "json", "yaml", "table"] [default: "table"]  --config-dir Path to config directory [string] [default: ""]  --api-key API key [string] [default: ""]  --analytics Manage analytics. Example: --no-analytics, --analytics false  [boolean] [default: true]  -v, --version Show version number [boolean]  -h, --help Show help [boolean]  Options: --context-file Context file [string] [default: (current-context-file)]

Commands

CommandSubcommandsDescription
authAuthenticate
meShow current user
orgslistManage organizations
projectslist, create, update, delete, getManage projects
ip-allowlist, add, remove, resetManage IP Allow
vpcendpoint, projectManage VPC endpoints and project VPC restrictions
brancheslist, create, reset, restore, rename, schema-diff, set-default, add-compute, delete, getManage branches
databaseslist, create, deleteManage databases
roleslist, create, deleteManage roles
operationslistManage operations
connection-stringGet connection string
set-contextSet context for session
completionGenerate a completion script

Global options

Global options are supported with any Neon CLI command.

OptionDescriptionTypeDefault
-o, --outputSet the Neon CLI output format (json, yaml, or table)stringtable
--config-dirPath to the Neon CLI configuration directorystring/home/<user>/.config/neonctl
--api-keyNeon API keystringNEON_API_KEY environment variable
--colorColorize the output. Example: --no-color, --color falsebooleantrue
--analyticsManage analyticsbooleantrue
-v, --versionShow the Neon CLI version numberboolean-
-h, --helpShow the Neon CLI helpboolean-

  • -o, --output

    Sets the output format. Supported options are json, yaml, and table. The default is table. Table output may be limited. The json and yaml output formats show all data.

    neon me --output json

  • --config-dir

    Specifies the path to the neonctl configuration directory. To view the default configuration directory containing you credentials.json file, run neon --help. The credentials file is created when you authenticate using the neon auth command. This option is only necessary if you move your neonctl configuration file to a location other than the default.

    neon projects list --config-dir /home/<user>/.config/neonctl

  • --api-key

    Specifies your Neon API key. You can authenticate using a Neon API key when running a Neon CLI command instead of using neon auth. For information about obtaining an Neon API key, see Create an API key.

    neon <command> --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>

    The authentication flow for the Neon CLI follows this order:

    • If the --api-key option is provided, it takes precedence and is used for authentication.
    • If the --api-key option is not provided, the NEON_API_KEY environment variable is used if it is set.
    • If both --api-key option and NEON_API_KEY environment variable are not provided or set, the CLI falls back to the credentials.json file created by the neon auth command.
    • If the credentials file is not found, the Neon CLI initiates the neon auth web authentication process.

  • --color

    Colorize the output. This option is enabled by default, but you can disable it by specifying --no-color or --color false, which is useful when using Neon CLI commands in your automation pipelines.

  • --analytics

    Analytics are enabled by default to gather information about the CLI commands and options that are used by our customers. This data collection assists in offering support, and allows for a better understanding of typical usage patterns so that we can improve user experience. Neon does not collect user-defined data, such as project IDs or command payloads. To opt-out of analytics data collection, specify --no-analytics or --analytics false.

  • -v, --version

    Shows the Neon CLI version number.

    $ neon --version 1.15.0

  • -h, --help

    Shows the neon command-line help. You can view help for neon, a neon command, or a neon subcommand, as shown in the following examples:

    neon --help  neon branches --help  neon branches create --help

Options

OptionDescriptionTypeDefault
--context-fileThe context file for CLI sessionsstringcurrent-context-file

  • --context-file

    Sets a background context for your CLI sessions, letting you perform organization, project, or branch-specific actions without having to specify the relevant id in every command. For example, this command lists all branches using the branches list command. No need to specify the project since the context file provides it.

    neon branches list --context-file path/to/context_file_name

    To define a context file, see Neon CLI commands — set-context.

GitHub repository

The GitHub repository for the Neon CLI is found here.