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 nam...

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.

Install the CLI
Choose your platform and install the Neon CLI:
- macOS
- Windows
- Linux
Install with Homebrew
Bash
brew install neonctl
Install via npm
Bash
npm i -g neon
Install with bun
Bash
bun install -g neon
Install via npm
Shell
npm i -g neon
Install with bun
Bash
bun install -g neon
Install via npm
Shell
npm i -g neon
Install with bun
Bash
bun install -g neon
Verify the installation by checking the CLI version:
Bash
```
neon --version
```
For the latest version, refer to the Neon CLI GitHub repository.
Authenticate
Authenticate with your Neon account using one of these methods:
Web Authentication (recommended)
Run the command below to authenticate through your browser:
Bash
```
neon login
```
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.
Bash
```
neon projects list --api-key <your-api-key>
```
To avoid entering your API key with each command, set it as an environment variable:
Bash
```
export NEON_API_KEY=<your-api-key>
```
For more about authenticating, see Neon CLI commands: login.
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.
Bash
```
neon link
```
You can also link non-interactively for scripts and CI. link writes a complete context, so pin a branch with --branch (or pass -y to pin the project's default branch):
Bash
```
neon link --org-id <your-org-id> --project-id <your-project-id> --branch main
```
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.
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.
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.
Either form of neon link creates a .neon file in your current directory with your project context.
Bash
```
cat .neon
```
JSON
```
{
  "projectId": "broad-surf-52155946",
  "orgId": "org-solid-base-83603457",
  "branch": "main"
}
```
Deprecated
Earlier versions of the CLI used neon set-context to write the .neon file directly. That command is deprecated in favor of neon link, prints a deprecation warning when you run it, and may be removed in a future release. Use neon link for new workflows.
Enable shell completion
Set up autocompletion to make using the CLI faster:
- Bash
- Zsh
Bash
neon completion >> ~/.bashrc source ~/.bashrc
Zsh
neon completion >> ~/.zshrc source ~/.zshrc
Now you can press Tab to complete Neon CLI commands and options. For further details, see Neon CLI commands: completion.
Common operations
List your projects
Bash
```
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
Bash
```
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:
Bash
```
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:
Bash
```
neon connection-string
```
For a specific branch, specify the branch name:
Bash
```
neon connection-string <branch-name>
```
To connect with psql directly, use the dedicated neon psql command:
Bash
```
neon psql
```
For more about the connection-string command, see Neon CLI commands: connection-string.
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.

List your projects

Create a branch

Get a connection string