> This page location: Tools & Workflows > API, CLI & SDKs > CLI > Quickstart > Full Neon documentation index: https://neon.com/docs/llms.txt > Summary: The Neon CLI quickstart installs neonctl on macOS, Windows, or Linux via Homebrew, npm, or bun, then authenticates using browser-based `neonctl auth` or a personal API key. Use this page when setting up terminal access to Neon for the first time, before working through the full CLI reference. It also covers the `.neon` context file (`neonctl set-context`) to avoid repeating `--project-id` and `--org-id` flags, shell tab completion, and first commands like `neonctl projects list`, `neonctl branches create`, and `neonctl connection-string`. # Neon CLI quickstart Get set up with the Neon CLI in just a few steps The Neon CLI lets you manage Neon directly from the terminal. This guide helps you set up and start using it. ## Install the CLI Choose your platform and install the Neon CLI: **macOS** **Install with Homebrew** ```bash brew install neonctl ``` **Install via npm** ```shell npm i -g neonctl ``` **Install with bun** ```bash bun install -g neonctl ``` **Windows** **Install via npm** ```shell npm i -g neonctl ``` **Install with bun** ```bash bun install -g neonctl ``` **Linux** **Install via npm** ```shell npm i -g neonctl ``` **Install with bun** ```bash bun install -g neonctl ``` Verify the installation by checking the CLI version: ```bash neonctl --version ``` For the latest version, refer to the [Neon CLI GitHub repository](https://github.com/neondatabase/neonctl). ## Authenticate Authenticate with your Neon account using one of these methods: **Web Authentication (recommended)** Run the command below to authenticate through your browser: ```bash neonctl 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](https://neon.com/docs/manage/api-keys#create-a-personal-api-key). ```bash neonctl projects list --api-key ``` To avoid entering your API key with each command, set it as an environment variable: ```bash export NEON_API_KEY= ``` For more about authenticating, see [Neon CLI commands: auth](https://neon.com/docs/cli/auth). ## Link your project The easiest way to set up CLI context is with [`neonctl link`](https://neon.com/docs/cli/link). It guides you through organization and project selection and writes a `.neon` context file in your project directory. Requires **neonctl 2.22.2** or later. ```bash neonctl link ``` You can also link non-interactively for scripts and CI: ```bash neonctl link --org-id --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 [`neonctl set-context`](https://neon.com/docs/cli/set-context): ```bash neonctl set-context --org-id --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. ```bash cat .neon ``` ```json { "projectId": "broad-surf-52155946", "orgId": "org-solid-base-83603457" } ``` You can also create named context files for different organization and project contexts: ```bash neonctl set-context --org-id --project-id --context-file dev_project ``` To switch contexts, add the `--context-file` option to any command: ```bash neonctl branches list --context-file Documents/dev_project ``` For more about the `set-context` command, see [Neon CLI commands: set-context](https://neon.com/docs/cli/set-context). ## Enable shell completion Set up autocompletion to make using the CLI faster: **Bash** ```bash neonctl completion >> ~/.bashrc source ~/.bashrc ``` **Zsh** ```bash neonctl completion >> ~/.zshrc source ~/.zshrc ``` Now you can press **Tab** to complete Neon CLI commands and options. For further details, see [Neon CLI commands: completion](https://neon.com/docs/cli/completion). ## Common operations ### List your projects ```bash neonctl 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](https://neon.com/docs/cli/projects). ### Create a branch ```bash neonctl branches create --name ``` Set your project context or specify `--project-id ` if you have more than one Neon project. To switch the active branch in your context file, use [`neonctl checkout`](https://neon.com/docs/cli/checkout): ```bash neonctl checkout ``` For more about the `branches` command, see [Neon CLI commands: branches](https://neon.com/docs/cli/branches). ### Get a connection string Get the connection string for the default branch in your project: ```bash neonctl connection-string ``` For a specific branch, specify the branch name: ```bash neonctl connection-string ``` To connect with `psql` directly, use the dedicated [`neonctl psql`](https://neon.com/docs/cli/psql) command: ```bash neonctl psql ``` For more about the `connection-string` command, see [Neon CLI commands: connection-string](https://neon.com/docs/cli/connection-string). ## Next steps Now that you're set up with the Neon CLI, you can: - Create more Neon projects with `neonctl projects create` - Manage your branches with various `neonctl branches` commands such as `reset`, `restore`, `rename`, `schema-diff`, and more - Create and manage databases with `neonctl databases` commands - Create and manage roles with `neonctl roles` commands - View the full set of Neon CLI commands available to you with `neonctl --help` For more details on all available commands, see the [CLI Reference](https://neon.com/docs/cli). --- ## Related docs (CLI) - [Overview](https://neon.com/docs/cli) - [Install and connect](https://neon.com/docs/cli/install)