> This page location: Tools & Workflows > API, CLI & SDKs > CLI > Overview > Full Neon documentation index: https://neon.com/docs/llms.txt > Summary: Neon CLI (neonctl) is the terminal tool for managing Neon projects, branches, databases, roles, and connection strings without using the web console. Use this page to install on macOS, Windows, or Linux via npm, Homebrew, bun, or standalone binary, and to find the full command reference with global options including --api-key, --output, and --context-file. # Neon CLI overview Overview of the Neon CLI: installation, commands, and options 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](https://neon.com/docs/reference/cli-quickstart). ## Install **macOS** **Install with [Homebrew](https://formulae.brew.sh/formula/neonctl)** ```bash brew install neonctl ``` **Install via [npm](https://www.npmjs.com/package/neonctl)** ```shell npm i -g neonctl ``` Requires [Node.js 18.0](https://nodejs.org/en/download/) or higher. **Install with bun** ```bash bun install -g neonctl ``` **macOS binary** Download the binary. No installation required. ```bash curl -sL https://github.com/neondatabase/neonctl/releases/latest/download/neonctl-macos -o neonctl ``` Run the CLI from the download directory: ```bash neon [options] ``` **Windows** **Install via [npm](https://www.npmjs.com/package/neonctl)** ```shell npm i -g neonctl ``` **Install with bun** ```bash bun install -g neonctl ``` Requires [Node.js 18.0](https://nodejs.org/en/download/) or higher. **Windows binary** Download the binary. No installation required. ```bash curl -sL -O https://github.com/neondatabase/neonctl/releases/latest/download/neonctl-win.exe ``` Run the CLI from the download directory: ```bash neonctl-win.exe [options] ``` **Linux** **Install via [npm](https://www.npmjs.com/package/neonctl)** ```shell npm i -g neonctl ``` **Install with bun** ```bash bun install -g neonctl ``` **Linux binary** Download the x64 or ARM64 binary, depending on your processor type. No installation required. x64: ```bash curl -sL https://github.com/neondatabase/neonctl/releases/latest/download/neonctl-linux-x64 -o neonctl ``` ARM64: ```bash curl -sL https://github.com/neondatabase/neonctl/releases/latest/download/neonctl-linux-arm64 -o neonctl ``` Run the CLI from the download directory: ```bash neon [options] ``` For more about installing, upgrading, and connecting, see [Neon CLI — Install and connect](https://neon.com/docs/reference/cli-install). **Note: 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: ```shell # npx npx neonctl # bunx bunx neonctl ``` ## Synopsis ```bash neon --help usage: neon [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 neon 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 psql [branch] Connect to a database via psql neon link Link the current directory to a Neon project neon checkout [id|name] Pin a branch in the local context (.neon) neon set-context Set the current context neon data-api Manage the Neon Data API for a database neon init Initialize Neon for AI assistants (MCP, skills, wizard) 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 | Command | Subcommands | Description | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | | [auth](https://neon.com/docs/reference/cli-auth) | | Authenticate | | [me](https://neon.com/docs/reference/cli-me) | | Show current user | | [orgs](https://neon.com/docs/reference/cli-orgs) | `list` | Manage organizations | | [projects](https://neon.com/docs/reference/cli-projects) | `list`, `create`, `update`, `delete`, `get` | Manage projects | | [ip-allow](https://neon.com/docs/reference/cli-ip-allow) | `list`, `add`, `remove`, `reset` | Manage IP Allow | | [vpc](https://neon.com/docs/reference/cli-vpc) | `endpoint`, `project` | Manage VPC endpoints and project VPC restrictions | | [branches](https://neon.com/docs/reference/cli-branches) | `list`, `create`, `reset`, `restore`, `rename`, `schema-diff`, `set-default`, `add-compute`, `delete`, `get` | Manage branches | | [databases](https://neon.com/docs/reference/cli-databases) | `list`, `create`, `delete` | Manage databases | | [roles](https://neon.com/docs/reference/cli-roles) | `list`, `create`, `delete` | Manage roles | | [operations](https://neon.com/docs/reference/cli-operations) | `list` | Manage operations | | [connection-string](https://neon.com/docs/reference/cli-connection-string) | | Get connection string | | [psql](https://neon.com/docs/reference/cli-psql) | | Connect to a database via psql | | [link](https://neon.com/docs/reference/cli-link) | | Link a directory to a Neon project | | [checkout](https://neon.com/docs/reference/cli-checkout) | | Pin a branch in `.neon` | | [set-context](https://neon.com/docs/reference/cli-set-context) | | Set context for session | | [data-api](https://neon.com/docs/reference/cli-data-api) | `create`, `get`, `update`, `refresh-schema`, `delete` | Manage the Neon Data API | | [init](https://neon.com/docs/reference/cli-init) | | Init Neon for AI assistants (MCP, agent skills, wizard) | | [completion](https://neon.com/docs/reference/cli-completion) | | Generate a completion script | ## Global options Global options are supported with any Neon CLI command. | Option | Description | Type | Default | | :------------------------------------------------------------------ | :---------------------------------------------------------- | :------ | :---------------------------------- | | [-o, --output](https://neon.com/docs/reference/neon-cli#output) | Set the Neon CLI output format (`json`, `yaml`, or `table`) | string | table | | [--config-dir](https://neon.com/docs/reference/neon-cli#config-dir) | Path to the Neon CLI configuration directory | string | `/home//.config/neonctl` | | [--api-key](https://neon.com/docs/reference/neon-cli#api-key) | Neon API key | string | `NEON_API_KEY` environment variable | | [--color](https://neon.com/docs/reference/neon-cli#color) | Colorize the output. Example: `--no-color`, `--color false` | boolean | true | | [--analytics](https://neon.com/docs/reference/neon-cli#analytics) | Manage analytics | boolean | true | | [-v, --version](https://neon.com/docs/reference/neon-cli#version) | Show the Neon CLI version number | boolean | - | | [-h, --help](https://neon.com/docs/reference/neon-cli#help) | Show the Neon CLI help | boolean | - | - `-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. ```bash 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. ```bash neon projects list --config-dir /home//.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](https://neon.com/docs/manage/api-keys#create-an-api-key). ```bash 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. ```bash export 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. ```bash $ 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: ```bash neon --help neon branches --help neon branches create --help ``` ## Options | Option | Description | Type | Default | | :---------------------------------------------------------------------- | :-------------------------------- | :----- | :------------------- | | [--context-file](https://neon.com/docs/reference/neon-cli#context-file) | The context file for CLI sessions | string | current-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. ```bash neon branches list --context-file path/to/context_file_name ``` To define a context file, see [Neon CLI commands — set-context](https://neon.com/docs/reference/cli-set-context). ## GitHub repository The GitHub repository for the Neon CLI is found [here](https://github.com/neondatabase/neonctl). --- ## Related docs (CLI) - [Quickstart](https://neon.com/docs/reference/cli-quickstart) - [Install and connect](https://neon.com/docs/reference/cli-install) - [auth](https://neon.com/docs/reference/cli-auth) - [me](https://neon.com/docs/reference/cli-me) - [orgs](https://neon.com/docs/reference/cli-orgs) - [projects](https://neon.com/docs/reference/cli-projects) - [ip-allow](https://neon.com/docs/reference/cli-ip-allow) - [vpc](https://neon.com/docs/reference/cli-vpc) - [branches](https://neon.com/docs/reference/cli-branches) - [checkout](https://neon.com/docs/reference/cli-checkout) - [databases](https://neon.com/docs/reference/cli-databases) - [roles](https://neon.com/docs/reference/cli-roles) - [operations](https://neon.com/docs/reference/cli-operations) - [connection-string](https://neon.com/docs/reference/cli-connection-string) - [psql](https://neon.com/docs/reference/cli-psql) - [link](https://neon.com/docs/reference/cli-link) - [set-context](https://neon.com/docs/reference/cli-set-context) - [data-api](https://neon.com/docs/reference/cli-data-api) - [init](https://neon.com/docs/reference/cli-init) - [completion](https://neon.com/docs/reference/cli-completion)