Inspect project branches
Review available development, staging, and production branches from a terminal.
Neon · Command
neonctl branches list
Lists branches in a Neon project. It supports optional project selection and richer JSON output in addition to the default table format.
How it works
Run this command to retrieve the branches belonging to a Neon project. Without a project identifier, it uses the project associated with the current Neon context; the default table view shows branch identity, state, expiration, and creation time, while JSON output provides additional details.
Syntax
neon branches list [options]Parameters
| Name | Type | Description |
|---|---|---|
--project-id | string | Project ID; optional string identifying the Neon project. |
--output | string | Selects the output format, including JSON output. |
Returns
A list of project branches, displayed by default as a table or, with --output json, as JSON containing more information.
Key points
- The command retrieves the branches belonging to a Neon project.
- Its command signature accepts optional command-line options.
- Use --project-id to target a particular project; the option accepts a string and is not required.
- When no output format is chosen, results are displayed as a table.
- The table presents branch name, identifier, state, expiration, and creation timestamps.
- Branch names can carry text labels that communicate status.
Common mistakes
- The default table output is less detailed than JSON output; use --output json when you need additional branch fields.
- The [current] label reflects the branch pinned in the local .neon context, not necessarily the project's default branch.
Example: List a project's branches
neon branches list --project-id solitary-leaf-288182Lists the branches in the specified Neon project using the default table format.
When to use it
Automate with JSON output
Feed complete branch metadata into a script or CI job.
Check branch status labels
Confirm which branch is default, protected, anonymized, or locally pinned.
Interview questions
QWhat does neon branches list do, and what is its syntax?
The command is neon branches list [options]. It lists branches in a Neon project, and --project-id optionally selects the project.
Follow-up: How would you inspect fields omitted from the table? Use --output json, which returns more information than the default table format.
QHow can the target project be selected?
The default output format is a table. A project ID can be supplied with --project-id, and the option is optional.
Follow-up: What should you do if the table lacks a field needed by automation? Request JSON output with --output json.
QWhat information and labels appear in the output?
The table includes branch name, ID, current state, expiration, and creation time. Text labels identify statuses such as default, protected, anonymized, and current.
Follow-up: How is the current label determined? It marks the branch pinned in the local .neon context file.
Related
neon branchesneon branches getneon branches create