---
title: Branching with the Neon CLI
subtitle: Learn how to create and delete branches with the Neon CLI
enableTableOfContents: true
updatedOn: '2025-08-07T17:19:33.979Z'
---
The examples in this guide demonstrate creating, viewing, and deleting branches using the Neon CLI. For other branch-related CLI commands, refer to [Neon CLI commands — branches](/docs/reference/cli-branches). This guide also describes how to use the `--api-key` option to authenticate CLI branching commands from the command line.
The examples show the default `table` output format. The Neon CLI also supports `json` and `yaml` output formats. For example, if you prefer output in `json`, add `--output json` to your Neon CLI command.
## Prerequisites
- The Neon CLI. See [Install the Neon CLI](/docs/reference/cli-install) for instructions.
- To run CLI commands, you must either authenticate through your browser or supply an API key using the `--api-key` option. See [Connect with the Neon CLI](/docs/reference/neon-cli#connect).
## Create a branch with the CLI
The following Neon CLI command creates a branch. If your Neon account has more than one project, you will be required to specify a project ID using the `--project-id` option. To view the CLI documentation for this command, refer to the [Neon CLI reference](/docs/reference/cli-branches#create).
The command response includes the branch ID, the compute endpoint ID, and the connection URI for connecting to the branch.
You can use the `--name` option with a `neon branches create` command to specify your own branch name instead of using the name generated by Neon. For example: `neon branches create --name mybranch`. Also, for any Neon CLI command, you can specify `--output json` to change the command output from the default table format to JSON format.
```bash
neon branches create
branch
┌───────────────────────┬───────────────────────┬─────────┬──────────────────────┬──────────────────────┐
│ Id │ Name │ Default │ Created At │ Updated At │
├───────────────────────┼───────────────────────┼─────────┼──────────────────────┼──────────────────────┤
│ br-lucky-mud-08878834 │ br-lucky-mud-08878834 │ false │ 2023-07-24T20:22:42Z │ 2023-07-24T20:22:42Z │
└───────────────────────┴───────────────────────┴─────────┴──────────────────────┴──────────────────────┘
endpoints
┌────────────────────────┬──────────────────────┐
│ Id │ Created At │
├────────────────────────┼──────────────────────┤
│ ep-mute-voice-52609794 │ 2023-07-24T20:22:42Z │
└────────────────────────┴──────────────────────┘
connection_uris
┌───────────────────────────────────────────────────────────────────────────────────────┐
│ Connection Uri │
├───────────────────────────────────────────────────────────────────────────────────────┤
│ postgresql://[user]:[password]@[neon_hostname]/[dbname] │
└───────────────────────────────────────────────────────────────────────────────────────┘
```
The Neon CLI provides a `neon connection-string` command you can use to extract a connection uri programmatically. See [Neon CLI commands — connection-string](/docs/reference/cli-connection-string).
## Create a branch from a non-default parent
Using the option `--parent`, you can specify any non-default branch that you want to use as the parent for your new branch, depending on the needs of your development workflow.
In this example, we're creating a hotfix branch called `hotfix/critical-fix` using the `development` branch as the parent:
```bash shouldWrap
neon branches create --name hotfix/critical-fix --parent development --project-id crimson-voice-12345678
branch
┌───────────────────────┬─────────────┬─────────┬──────────────────────┬──────────────────────┐
│ Id │ Name │ Default │ Created At │ Updated At │
├───────────────────────┼─────────────┼─────────┼──────────────────────┼──────────────────────┤
│ br-misty-mud-a5poo34s │ hotfix/critical-fix │ false │ 2024-04-23T17:04:10Z │ 2024-04-23T17:04:10Z │
└───────────────────────┴─────────────┴─────────┴──────────────────────┴──────────────────────┘
endpoints
┌──────────────────────────┬──────────────────────┐
│ Id │ Created At │
├──────────────────────────┼──────────────────────┤
│ ep-orange-heart-123456 │ 2024-04-23T17:04:10Z │
└──────────────────────────┴──────────────────────┘
connection_uris
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Connection Uri │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ postgresql://neondb_owner:123456@ep-orange-heart-a54grm9j.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```
## List branches with the CLI
The following Neon CLI command lists all branches in your Neon project, as well as any branches shared with you. If your Neon account has more than one project, you will be required to specify a project ID using the `--project-id` option. To view the CLI documentation for this method, refer to the [Neon CLI reference](/docs/reference/cli-branches#list).
```bash
neon projects list
Projects
┌────────────────────────┬────────────────────┬───────────────┬──────────────────────┐
│ Id │ Name │ Region Id │ Created At │
├────────────────────────┼────────────────────┼───────────────┼──────────────────────┤
│ crimson-voice-12345678 │ frontend │ aws-us-east-2 │ 2024-04-15T11:17:30Z │
├────────────────────────┼────────────────────┼───────────────┼──────────────────────┤
│ calm-thunder-12121212 │ backend │ aws-us-east-2 │ 2024-04-10T15:21:01Z │
├────────────────────────┼────────────────────┼───────────────┼──────────────────────┤
│ nameless-hall-87654321 │ billing │ aws-us-east-2 │ 2024-04-10T14:35:17Z │
└────────────────────────┴────────────────────┴───────────────┴──────────────────────┘
Shared with you
┌───────────────────┬────────────────────┬──────────────────┬──────────────────────┐
│ Id │ Name │ Region Id │ Created At │
├───────────────────┼────────────────────┼──────────────────┼──────────────────────┤
│ noisy-fire-212121 │ API │ aws-eu-central-1 │ 2023-04-22T18:41:13Z │
└───────────────────┴────────────────────┴──────────────────┴──────────────────────┘
```
## Delete a branch with the CLI
The following Neon CLI command deletes the specified branch. If your Neon account has more than one project, you will be required to specify a project ID using the `--project-id` option. To view the CLI documentation for this command, refer to the [Neon CLI reference](/docs/reference/cli-branches#delete). You can delete a branch by its ID or name.
```bash
neon branches delete br-rough-sky-158193
┌───────────────────────┬───────────────────────┬─────────┬──────────────────────┬──────────────────────┐
│ Id │ Name │ Default │ Created At │ Updated At │
├───────────────────────┼───────────────────────┼─────────┼──────────────────────┼──────────────────────┤
│ br-lucky-mud-08878834 │ br-lucky-mud-08878834 │ false │ 2023-07-24T20:22:42Z │ 2023-07-24T20:44:51Z │
└───────────────────────┴───────────────────────┴─────────┴──────────────────────┴──────────────────────┘
```
## Branching automation with the Neon CLI
The Neon CLI enables easy automation of branching operations for integration into your workflows or toolchains. To facilitate authentication to Neon when running a CLI command, the Neon CLI allows you to use an API key. For information about obtaining an API key, see [Create an API key](/docs/manage/api-keys#create-an-api-key).
To use an API key, you can store it in an environment variable on your system. This prevents the key from being hardcoded into your automation scripts or exposed in another way. For example, you can add the following line to your shell's profile file (`.bashrc` or `.bash_profile` for bash shell):
```bash
export NEON_API_KEY=
```
After exporting your key, source the profile file (source `~/.bashrc` or source `~/.bash_profile`), or start a new terminal session.
You do not need to specify the variable name explicitly when using a Neon CLI command. A Neon CLI command looks for a `NEON_API_KEY` variable setting by default.
This API key configuration ensures that the API key is kept secure while still providing a way to authenticate your CLI commands. Remember, you should handle your API key with the same level of security as your other credentials.
## Branch expiration
For temporary environments, create branches with `--expires-at` to set a TTL for automatic deletion instead of manual cleanup:
```bash shouldWrap
# Create a branch that expires at a specific date and time
neon branches create --project-id --name ci-test --parent --expires-at "2025-07-15T18:02:16Z"
# Create a branch that expires in 2 hours (Linux/GNU)
neon branches create --project-id --name ci-test --parent --expires-at "$(date -u -d '+2 hours' +%Y-%m-%dT%H:%M:%SZ)"
# Create a branch that expires in 2 hours (macOS/BSD)
neon branches create --project-id --name ci-test --parent --expires-at "$(date -u -v+2H +%Y-%m-%dT%H:%M:%SZ)"
```
You can also update or remove expiration from existing branches:
```bash shouldWrap
# Update expiration to a new timestamp
neon branches set-expiration --expires-at "2025-07-20T12:00:00Z" --project-id
# Remove expiration from a branch
neon branches set-expiration --expires-at null --project-id
```
For details and configuration instructions, refer to our [Branch expiration guide](/docs/guides/branch-expiration).
## Resetting a branch from its parent
Depending on your development workflow, you might need to periodically reset a branch to match the latest state of its parent. This is useful, for example, when resetting a development branch back to the production branch before starting work on a new feature.
Use the following command to reset a branch to the current state (HEAD) of its parent branch:
```bash
neon branches reset --parent
```
Example:
This example resets a feature branch to match the latest state of its parent branch:
```bash
neon branches reset feature/user-auth --parent
┌────────────────────────────┬───────────────────┬─────────┬──────────────────────┬──────────────────────┐
│ Id │ Name │ Default │ Created At │ Last Reset At │
├────────────────────────────┼───────────────────┼─────────┼──────────────────────┼──────────────────────┤
│ br-twilight-smoke-123456 │ feature/user-auth │ false │ 2024-04-23T17:01:49Z │ 2024-04-23T17:57:35Z │
```
**Branch expiration behavior:** When you reset a branch that has an expiration set, the expiration timer restarts from the reset time using the original duration. For example, if your branch was originally set to expire in 24 hours, resetting gives it another full 24 hours from the reset time. This process recalculates the new `expires_at` value using the preserved `ttl_interval_seconds`, but the TTL interval itself remains unchanged. For more details, see [branch expiration](/docs/guides/branch-expiration).
If the branch you want to reset has child branches, you need to include the `preserve-under-name` parameter. This will save the current state of your branch under a new name before performing the reset. The child branches will then show this newly named branch as their parent. This step ensures that your original branch can be reset cleanly, as all child branches will have been transferred to the new parent name.
For example, here we are resetting `feature/user-auth` to its parent while preserving its latest state under the branch name `feature/user-auth-backup`:
```bash
neon branches reset feature/user-auth --parent --preserve-under-name feature/user-auth-backup
┌────────────────────────────┬──────────┬─────────┬──────────────────────┬──────────────────────┐
│ Id │ Name │ Default │ Created At │ Last Reset At │
├────────────────────────────┼──────────┼─────────┼──────────────────────┼──────────────────────┤
│ br-twilight-smoke-a5ofkxry │ feature/user-auth │ false │ 2024-04-23T17:01:49Z │ 2024-04-23T18:02:36Z │
```
For more details, see [Reset from parent](/docs/guides/reset-from-parent).
## Restoring a branch to its own or another branch's history
Using the CLI, you can restore a branch to an earlier point in its history or another branch's history using the following command:
```bash shouldWrap
neon branches restore
```
This command restores the branch `production` to an earlier timestamp in its own history, saving to a backup branch called `production_restore_backup_2024-02-20`
```bash
neon branches restore production ^self@2024-05-06T10:00:00.000Z --preserve-under-name production_restore_backup_2024-05-06
```
Results of the operation:
```bash shouldWrap
INFO: Restoring branch br-purple-dust-a5hok5mk to the branch br-purple-dust-a5hok5mk timestamp 2024-05-06T10:00:00.000Z
Restored branch
┌─────────────────────────┬──────┬──────────────────────┐
│ Id │ Name │ Last Reset At │
├─────────────────────────┼──────┼──────────────────────┤
│ br-purple-dust-a5hok5mk │ main │ 2024-05-07T09:45:21Z │
└─────────────────────────┴──────┴──────────────────────┘
Backup branch
┌─────────────────────────┬────────────────────────────────┐
│ Id │ Name │
├─────────────────────────┼────────────────────────────────┤
│ br-flat-forest-a5z016gm │ production_restore_backup_2024-05-06 │
└─────────────────────────┴────────────────────────────────┘
```
For full details about the different restore options available with this command, see [Restoring using the CLI](/docs/guides/branch-restore#how-to-use-branch-restore).