Neon CLI quickstart

The Neon CLI lets you manage Neon directly from the terminal. This guide helps you set up and start using it. The CLI is invoked as neon; neonctl is an alias for neon, so commands work with either name.

1. Install the CLI

   Choose your platform and install the Neon CLI:

   macOSWindowsLinux

   Install with Homebrew

   brew install neonctl

   Install via npm

   npm i -g neon

   Install with bun

   bun install -g neon

   Verify the installation by checking the CLI version:

   neon --version

   For the latest version, refer to the Neon CLI GitHub repository.

2. Authenticate

   Authenticate with your Neon account using one of these methods:

   Web Authentication (recommended)

   Run the command below to authenticate through your browser:

   neon auth

   This opens a browser window where you can authorize the CLI to access your Neon account.

   API Key Authentication

   Alternatively, use a personal Neon API key, which you can create in the Neon Console. See Create a personal API key.

   neon projects list --api-key <your-api-key>

   To avoid entering your API key with each command, set it as an environment variable:

   export NEON_API_KEY=<your-api-key>

   For more about authenticating, see Neon CLI commands: auth.

3. Link your project

   The easiest way to set up CLI context is with neon link. It guides you through organization and project selection and writes a .neon context file in your project directory. Requires neon 2.22.2 or later.

   neon link

   You can also link non-interactively for scripts and CI:

   neon link --org-id <your-org-id> --project-id <your-project-id>

   tip

   If you run a CLI command without an organization context, the CLI prompts you to select an organization and offers to save it as your default, creating a .neon context file automatically.

   tip

   Once linked, you can run CLI commands from any subdirectory of your project; the CLI walks up parent folders to find the .neon file. The file is also automatically added to .gitignore so it's not committed by accident.

   Alternatively, set context manually with neon set-context:

   neon set-context --org-id <your-org-id> --project-id <your-project-id>

   info

   You can find your organization ID in the Neon Console by selecting your organization and navigating to Settings. You can find your Neon project ID by opening your project in the Neon Console and navigating to Settings > General.

   The set-context command creates a .neon file in your current directory with your project context.

   cat .neon

   {
     "projectId": "broad-surf-52155946",
     "orgId": "org-solid-base-83603457"
   }

   You can also create named context files for different organization and project contexts:

   neon set-context --org-id <your-org-id> --project-id <your-project-id> --context-file dev_project

   To switch contexts, add the --context-file option to any command:

   neon branches list --context-file Documents/dev_project

   For more about the set-context command, see Neon CLI commands: set-context.

4. Enable shell completion

   Set up autocompletion to make using the CLI faster:

   BashZsh

   neon completion >> ~/.bashrc
   source ~/.bashrc

   Now you can press Tab to complete Neon CLI commands and options. For further details, see Neon CLI commands: completion.

5. Common operations

   List your projects

   neon projects list

   If no organization context is set, the CLI prompts you to select an organization.

   For more about the projects command, see Neon CLI commands: projects.

   Create a branch

   neon branches create --name <branch-name>

   Set your project context or specify --project-id <your-project-id> if you have more than one Neon project.

   To switch the active branch in your context file, use neon checkout:

   neon checkout <branch>

   For more about the branches command, see Neon CLI commands: branches.

   Get a connection string

   Get the connection string for the default branch in your project:

   neon connection-string

   For a specific branch, specify the branch name:

   neon connection-string <branch-name>

   To connect with psql directly, use the dedicated neon psql command:

   neon psql

   For more about the connection-string command, see Neon CLI commands: connection-string.

6. Next steps

   Now that you're set up with the Neon CLI, you can:

   • Create more Neon projects with neon projects create
   • Manage your branches with various neon branches commands such as reset, restore, rename, schema-diff, and more
   • Create and manage databases with neon databases commands
   • Create and manage roles with neon roles commands
   • View the full set of Neon CLI commands available to you with neon --help

   For more details on all available commands, see the CLI Reference.