Skip to main content
Build your agent on Neon and provision backends you fully control. See how Ideavo does it
/APIs & SDKs/Projects and branches/branches

Neon CLI command: branches

List, create, rename, and delete branches; set default; run schema diff

View as Markdown

The branches command lists, creates, renames, deletes, and retrieves details about branches in your Neon project. It also sets the default branch, adds a compute or read replica to a branch, restores a branch to an earlier point in time, and runs a schema diff between branches. For information about branches in Neon, see Manage branches. If --project-id is omitted, the CLI resolves it from your context file, auto-selects when your account has only one project, and otherwise asks you to pass --project-id.

Switch the active branch

To pin a branch in your local .neon context file so subsequent commands target it, use neon checkout.

Subcommands: add-compute, create, delete, get, list, rename, reset, restore, schema-diff, set-default, set-expiration

neon branches list

Lists branches in a Neon project.

neon branches list [options]
OptionDescriptionTypeDefaultRequired
--project-idProject IDstring—No

List branches with the default table output format:

neon branches list --project-id solitary-leaf-288182
Output
Name                   ID                     Current State  Expires At  Created At
[default] production   br-wispy-cloud-123456  ready          never       2026-09-30T13:15:12Z
[current] development  br-cool-forest-123456  ready          never       2026-09-30T14:45:50Z

Branch names include text labels that indicate status: [default] marks the project's default branch, [protected] marks a protected branch, [anon] marks an anonymized branch, and [current] marks the branch pinned in your local .neon context file.

List branches with --output json, which returns more information than the table format:

neon branches list --project-id solitary-leaf-288182 --output json
Show output
[
  {
    "id": "br-wild-boat-123456",
    "project_id": "solitary-leaf-288182",
    "name": "production",
    "current_state": "ready",
    "logical_size": 29515776,
    "creation_source": "console",
    "default": true,
    "cpu_used_sec": 78,
    "compute_time_seconds": 78,
    "active_time_seconds": 312,
    "written_data_bytes": 107816,
    "data_transfer_bytes": 0,
    "created_at": "2026-07-09T17:01:34Z",
    "updated_at": "2026-07-09T17:15:13Z"
  },
  {
    "id": "br-shy-cake-123456",
    "project_id": "solitary-leaf-288182",
    "parent_id": "br-wild-boat-123456",
    "parent_lsn": "0/1E88838",
    "name": "development",
    "current_state": "ready",
    "creation_source": "console",
    "default": false,
    "cpu_used_sec": 0,
    "compute_time_seconds": 0,
    "active_time_seconds": 0,
    "written_data_bytes": 0,
    "data_transfer_bytes": 0,
    "created_at": "2026-07-09T17:37:10Z",
    "updated_at": "2026-07-09T17:37:10Z"
  }
]

neon branches create

Creates a branch in a Neon project.

neon branches create [options]
OptionDescriptionTypeDefaultRequired
--computeCreate a branch with or without a compute. By default branch is created with a read-write compute. To create a branch without compute use --no-computebooleantrueNo
--cuThe number of Compute Units. Could be a fixed size (e.g. "2") or a range delimited by a dash (e.g. "0.5-3").stringproject defaultNo
--expires-atSet an expiration date for the branch. Accepts a date string (e.g., 2024-12-31T23:59:59Z).stringnever expiresNo
--nameThe branch namestringbranch idNo
--parentParent branch name or id or timestamp or LSN. Defaults to the default branchstring—No
--protectedWhether the branch is protected. Protected branches (and their computes) cannot be deleted, archived, or reset, and block deletion of the project. Can be gated by protected_branches_only in the IP allowlist. Paid plans only.boolean—No
--psqlConnect to a new branch via psqlbooleanfalseNo
--schema-onlyCreate a schema-only branch. Requires exactly one read-write compute.booleanfalseNo
--secretsInclude connection credentials in command output. Use --no-secrets to omit thembooleantrueNo
--suspend-timeoutDuration of inactivity in seconds after which the compute endpoint is automatically suspended. The value 0 means use the global default. The value -1 means never suspend. The default value is 300 seconds (5 minutes). The maximum value is 604800 seconds (1 week).number0No
--typeType of compute to addstringread_writeNo
--project-idProject IDstring—No

The --name value must be unique within the project and can be up to 256 characters; see Branch naming requirements. A read_only compute is a read replica.

note

When creating a branch from a protected parent branch, role passwords on the child branch are changed. For more information about this Protected Branches feature, see New passwords generated for Postgres roles on child branches.

neon branches create
Output
Branch
Name           br-mute-sunset-123456
ID             br-mute-sunset-123456
Current State  ready
Created At     2026-09-30T20:07:27Z

Compute
ID                       Created At
ep-floral-violet-123456  2026-09-30T20:07:27Z

Connection string
Connection URI
postgresql://[user]:[password]@[neon_hostname]/[dbname]

note

If the parent branch has more than one role or database, the branches create command does not output a connection URI. As an alternative, you can use the connection-string command to retrieve the connection URI for a branch. This command includes options for specifying the role and database. See the connection-string command.

Omit the connection string from the output, keeping it out of terminal scrollback and CI logs:

neon branches create --no-secrets

Needs Neon CLI 4.9.0+; older versions ignore --no-secrets and still print the connection string.

Create a branch with --output json, which returns the full branch response data:

neon branches create --output json
Show output
{
  "branch": {
    "id": "br-frosty-art-123456",
    "project_id": "polished-shape-60485499",
    "parent_id": "br-polished-fire-123456",
    "parent_lsn": "0/1E887C8",
    "name": "br-frosty-art-123456",
    "current_state": "init",
    "pending_state": "ready",
    "creation_source": "neon",
    "default": false,
    "cpu_used_sec": 0,
    "compute_time_seconds": 0,
    "active_time_seconds": 0,
    "written_data_bytes": 0,
    "data_transfer_bytes": 0,
    "created_at": "2026-08-03T20:12:24Z",
    "updated_at": "2026-08-03T20:12:24Z"
  },
  "endpoints": [
    {
      "host": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
      "id": "ep-cool-darkness-123456",
      "project_id": "polished-shape-60485499",
      "branch_id": "br-frosty-art-123456",
      "autoscaling_limit_min_cu": 1,
      "autoscaling_limit_max_cu": 1,
      "region_id": "aws-us-east-2",
      "type": "read_write",
      "current_state": "init",
      "pending_state": "active",
      "settings": {},
      "pooler_enabled": false,
      "pooler_mode": "transaction",
      "disabled": false,
      "passwordless_access": true,
      "creation_source": "neon",
      "created_at": "2026-08-03T20:12:24Z",
      "updated_at": "2026-08-03T20:12:24Z",
      "proxy_host": "us-east-2.aws.neon.tech",
      "suspend_timeout_seconds": 0,
      "provisioner": "k8s-pod"
    }
  ],
  "connection_uris": [
    {
      "connection_uri": "postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require",
      "connection_parameters": {
        "database": "dbname",
        "password": "AbC123dEf",
        "role": "alex",
        "host": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
        "pooler_host": "ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech"
      }
    }
  ]
}

Create a branch with a user-defined name:

neon branches create --name feature/user-auth

Set the compute size when creating a branch:

neon branches create --name mybranch --cu 2

Set the compute's autoscaling range when creating a branch:

neon branches create --name mybranch --cu 0.5-3

Create a branch with a read replica compute:

neon branches create --name my_read_replica_branch --type read_only

Create a branch from a parent branch other than your main branch:

neon branches create --name feature/payment-api --parent development

Create an instant restore branch by specifying the --parent option with a timestamp:

neon branches create --name data_recovery --parent 2023-07-11T10:00:00Z

The timestamp must be in RFC 3339 format (this timestamp converter can help). For more about instant restore, see Instant restore.

Create a branch and connect to it with psql immediately. Arguments after -- are passed through to psql, so you can run an .sql file or a query on creation:

neon branches create --psql
neon branches create --psql -- -f dump.sql
neon branches create --psql -- -c "SELECT version()"

Create a schema-only branch:

neon branches create --schema-only

Create a protected branch:

neon branches create --name production --protected

neon branches reset

Resets a child branch to the latest data from its parent. The <id|name> is the branch ID or branch name; either works.

neon branches reset <id|name> [options]
OptionDescriptionTypeDefaultRequired
--parentReset to a parent branchbooleanfalseNo
--preserve-under-nameName under which to preserve the old branch—No
--project-idProject IDstring—No

The --parent option is required; resetting from the parent branch is currently the only supported reset operation. To rewind a branch to an earlier point in time, see restore.

neon branches reset development --parent
Output
Name           development
ID             br-cool-forest-123456
Current State  ready
Created At     2026-09-30T14:45:50Z
Last Reset At  2026-09-30T15:36:32Z

neon branches restore

Restores a branch to a specified point in time in its own or another branch's history. The <target-id|name> is the ID or name of the branch you want to restore, and <source> is the source branch you want to restore from. Source options are:

  • ^self: restores the selected branch to an earlier point in its own history. You must specify a timestamp or LSN (restoring to head is not supported).
  • ^parent: restores the target branch to its parent. By default the target is restored to the latest (head) of its parent. Append @timestamp or @lsn to restore to an earlier point in the parent's history.
  • A source branch ID or name: restores the target branch to the selected source branch. It restores the latest (head) by default. Append @timestamp or @lsn to restore to an earlier point in the source branch's history.
neon branches restore <target-id|name> <source>[@(timestamp|lsn)]
OptionDescriptionTypeDefaultRequired
--preserve-under-nameName under which to preserve the old branch—No
--project-idProject IDstring—No

The --preserve-under-name option is required when restoring to ^self.

Restore main to an earlier point in its own history, saving the previous state to a backup branch named main_restore_backup_2026-09-29:

neon branches restore main ^self@2026-09-29T10:00:00.000Z --preserve-under-name main_restore_backup_2026-09-29
Output
Restoring main to main at timestamp 2026-09-29T10:00:00.000Z
Restored branch
ID             br-purple-dust-123456
Name           main
Last Reset At  2026-09-30T09:45:21Z

Backup branch
ID    br-flat-forest-123456
Name  main_restore_backup_2026-09-29

Restore the target branch feature/user-auth to the head of the source branch main:

neon branches restore feature/user-auth main
Output
Restoring feature/user-auth to the head of main
Restored branch
ID             br-restless-frost-123456
Name           feature/user-auth
Last Reset At  2026-09-30T15:42:34Z

Restore feature/user-auth to an earlier point in time from its parent branch:

neon branches restore feature/user-auth ^parent@2026-09-29T10:30:00.000Z
Output
Restoring feature/user-auth to main at timestamp 2026-09-29T10:30:00.000Z
Restored branch
ID             br-restless-frost-123456
Name           feature/user-auth
Last Reset At  2026-09-30T15:55:04Z

neon branches rename

Renames a branch.

neon branches rename <id|name> <new-name> [options]
OptionDescriptionTypeDefaultRequired
--project-idProject IDstring—No

The new name follows the same rules as --name on branches create; see Branch naming requirements.

neon branches rename mybranch teambranch
Output
Name           teambranch
ID             br-rough-sound-123456
Current State  ready
Created At     2026-09-30T20:46:58Z

neon branches schema-diff

Compares the latest schemas of any two branches, or compares against a specific point in a branch's own or another branch's history.

For a git-style shortcut that defaults to comparing a branch against its parent, see neon diff.

The [base-branch] is the branch to compare against. It's optional; if omitted, the command uses the branch from your set-context file, or the project's default branch if no context is configured.

The [compare-source] specifies the branch or state to compare against. Options are:

  • ^self: compares the selected branch to an earlier point in its own history. You must specify a timestamp or LSN.
  • ^parent: compares the selected branch to the head of its parent branch. You can append @timestamp or @lsn to compare to an earlier point in the parent's history.
  • A branch ID or name: compares the selected branch to the head of another specified branch. Append @timestamp or @lsn to compare to an earlier point in the specified branch's history.
neon branches schema-diff [base-branch] [compare-source[@(timestamp|lsn)]] [options]
OptionDescriptionTypeDefaultRequired
--database, --dbName of the database for which the schema comparison is performedstring—No
--project-idProject IDstring—No

note

Use the --no-color or --color false global option to decolorize command output in CI/CD pipelines.

Compare the schema of the production branch to the head of the development branch:

neon branches schema-diff production development

The output indicates that in the table public.playing_with_neon, a new column description character varying(255) has been added in the development branch that is not present in the production branch.

Output
--- Database: neondb	(Branch: br-wandering-firefly-a50un462)
+++ Database: neondb	(Branch: br-fancy-sky-a5cydw8p)
@@ -26,9 +26,10 @@

 CREATE TABLE public.playing_with_neon (
     id integer NOT NULL,
     name text NOT NULL,
-    value real
+    value real,
+    description character varying(255)
 );

Compare the schema of feature/user-auth to an earlier point in its own history at LSN 0/123456:

neon branches schema-diff feature/user-auth ^self@0/123456

Compare the schema of feature/user-auth to the head of its parent branch:

neon branches schema-diff feature/user-auth ^parent

Compare the schema of the production branch to the state of feature/payment-api at timestamp 2024-06-01T00:00:00.000Z:

neon branches schema-diff production feature/payment-api@2024-06-01T00:00:00.000Z

neon branches set-default

Sets a branch as the default branch in your Neon project.

neon branches set-default <id|name> [options]
OptionDescriptionTypeDefaultRequired
--project-idProject IDstring—No
neon branches set-default mybranch
Output
Name           [default] mybranch
ID             br-odd-frog-123456
Current State  ready
Created At     2026-09-30T12:22:12Z

neon branches set-expiration

Sets or updates the expiration date for a branch. When the expiration time is reached, the branch and its compute endpoints are permanently deleted.

neon branches set-expiration <id|name> [options]
OptionDescriptionTypeDefaultRequired
--expires-atSet a expiration date for the branch. If omitted, expiration will be removed. Format [RFC3339]: 2024-12-31T23:59:59Zstring—No
--project-idProject IDstring—No

Set an expiration date for a branch:

neon branches set-expiration mybranch --expires-at 2025-08-15T18:00:00Z

Remove expiration from a branch (omit the parameter):

neon branches set-expiration mybranch

neon branches add-compute

Adds a compute to an existing branch in your Neon project.

neon branches add-compute <id|name> [options]
OptionDescriptionTypeDefaultRequired
--cuThe number of Compute Units. Could be a fixed size (e.g. "2") or a range delimited by a dash (e.g. "0.5-3").string—No
--nameOptional name of the computestring—No
--typeType of compute to addstringread_onlyNo
--project-idProject IDstring—No

A read_only compute is a read replica. A branch can have a single primary read-write compute and multiple read replica computes.

Add a read replica compute to a branch:

neon branches add-compute mybranch --type read_only
Output
ID    ep-rough-lab-123456
Host  ep-rough-lab-123456.us-east-2.aws.neon.tech

Set the compute size when adding a compute to a branch:

neon branches add-compute main --cu 2

Set the compute's autoscaling range when adding a compute to a branch:

neon branches add-compute main --cu 0.5-3

neon branches delete

Deletes a branch in a Neon project.

neon branches delete <id|name> [options]
OptionDescriptionTypeDefaultRequired
--project-idProject IDstring—No
neon branches delete br-rough-sky-123456
Output
Name           my_child_branch
ID             br-rough-sky-123456
Current State  ready
Created At     2026-09-30T20:57:39Z

neon branches get

Retrieves details about a branch.

neon branches get <id|name> [options]
OptionDescriptionTypeDefaultRequired
--project-idProject IDstring—No

Get a branch with the default table output format:

neon branches get production
Output
Name           [default] production
ID             br-wispy-cloud-123456
Current State  ready
Created At     2026-09-30T13:15:12Z
Logical Size   30.6 MiB

Get a branch with the --output format option set to json:

neon branches get production --output json
Show output
{
  "id": "br-lingering-bread-123456",
  "project_id": "noisy-rain-039137",
  "name": "production",
  "current_state": "ready",
  "logical_size": 29769728,
  "creation_source": "console",
  "default": false,
  "cpu_used_sec": 522,
  "compute_time_seconds": 522,
  "active_time_seconds": 2088,
  "written_data_bytes": 174433,
  "data_transfer_bytes": 20715,
  "created_at": "2026-06-28T10:17:28Z",
  "updated_at": "2026-07-11T12:22:59Z"
}

Last updated on

Was this page helpful?
Edit on GitHub