Neon CLI commands — branches
Use the Neon CLI to manage Neon directly from the terminal
Before you begin
- Before running the
branchescommand, ensure that you have installed the Neon CLI. - If you have not authenticated with the neonctl auth command, running a Neon CLI command automatically launches the Neon CLI browser authentication process. Alternatively, you can specify a Neon API key using the
--api-keyoption when running a command. See Connect.
The branches command
The branches command allows you to list, create, rename, delete, and retrieve information about branches in your Neon project. It also permits setting a branch as the primary branch and adding a compute endpoint to a branch. You can create a read replica by adding a read-only compute endpoint.
Usage
| Subcommand | Description |
|---|---|
| list | List branches |
| create | Create a branch |
| rename | Rename a branch |
| set-primary | Set a primary branch |
| add-compute | Add replica to a branch |
| delete | Delete a branch |
| get | Get a branch |
list
This subcommand allows you to list branches in a Neon project.
Usage
Options
In addition to the Neon CLI global options, the list subcommand supports this option:
| Option | Description | Type | Required |
|---|---|---|---|
--project-id | Project ID | string | Only if your Neon account has more than one project |
Examples
-
List branches with the default
tableoutput format. The information provided with this output format is limited compared to other formats, such asjson. -
List branches with the
jsonoutput format. This format provides more information than the defaulttableoutput format.
create
This subcommand allows you to create a branch in a Neon project.
Usage
Options
In addition to the Neon CLI global options, the create subcommand supports these options:
| Option | Description | Type | Required |
|---|---|---|---|
--project-id | Project ID | string | Only if your Neon account has more than one project |
--name | The branch name | string | |
--parent | Parent branch name, id, timestamp, or LSN. Defaults to the primary branch | string | |
--compute | Create a branch with or without a compute. By default, the branch is created with a read-write endpoint. The default value is true. To create a branch without a compute, use --no-compute | boolean | |
--type | Type of compute to add. Choices are read_write (the default) or read_only. A branch with a read-only compute endpoint is also referred to as a read replica. | string |
Examples
-
Create a branch:
tip
The Neon CLI provides a
neonctl connection-stringcommand you can use to extract a connection uri programmatically. See Neon CLI commands — connection-string. -
Create a branch with the
--outputformat of the command set tojson. This output format returns all of the branch response data, whereas the defaulttableoutput format (shown in the preceding example) is limited in the information it can display. -
Create a branch with a user-defined name:
- Create a branch with a read-only compute endpoint (a read replica)
- Create a branch from a parent branch other than your
mainbranch
- Create a point-in-time restore branch by specifying the
--parentoption with a timestamp:
The timestamp must be provided in ISO 8601 format. You can use this timestamp converter. For more information about point-in-time restore, see Branching — Point-in-time restore (PITR).
rename
This subcommand allows you to update a branch in a Neon project.
Usage
<id|name> refers to the Branch ID and branch name. You can specify one or the other.
Options
In addition to the Neon CLI global options, the rename subcommand supports this option:
| Option | Description | Type | Required |
|---|---|---|---|
| --project-id | Project ID | string | Only if your Neon account has more than one project |
Example
set-primary
This subcommand allows you to set a branch as the primary branch in your Neon project.
Usage
<id|name> refers to the Branch ID and branch name. You can specify one or the other.
Options
In addition to the Neon CLI global options, the set-primary subcommand supports this option:
| Option | Description | Type | Required |
|---|---|---|---|
| --project-id | Project ID | string | Only if your Neon account has more than one project |
Example
add-compute
This subcommand allows you to add a compute endpoint to an existing branch in your Neon project.
Usage
<id|name> refers to the Branch ID and branch name. You can specify one or the other.
Options
In addition to the Neon CLI global options, the add-compute subcommand supports these options:
| Option | Description | Type | Required |
|---|---|---|---|
--project-id | Project ID | string | Only if your Neon account has more than one project |
--type | Type of compute to add. Choices are read_only (the default) or read_write. A branch with a read-only compute endpoint is also referred to as a read replica. A branch can have a single read-write and multiple read-only compute endpoints. | string |
Example
delete
This subcommand allows you to delete a branch in a Neon project.
Usage
<id|name> refers to the Branch ID and branch name. You can specify one or the other.
Options
In addition to the Neon CLI global options, the delete subcommand supports this option:
| Option | Description | Type | Required |
|---|---|---|---|
| --project-id | Project ID | string | Only if your Neon account has more than one project |
Example
get
This subcommand allows you to retrieve details about a branch.
Usage
Options
In addition to the Neon CLI global options, the get subcommand supports this option:
Options
| Option | Description | Type | Required |
|---|---|---|---|
| --project-id | Project ID | string | Only if your Neon account has more than one project |
Examples
A get example with the --output format option set to json:
Need help?
Join the Neon community forum to ask questions or see what others are doing with Neon. Neon Pro Plan users can open a support ticket from the console. For more detail, see Getting Support.
Last updated on