> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# branches list

> List the branch names you can target with --branch

List an app's `main` branch and its active branches. Use this to find the exact name to pass to the [`--branch`](/developers/references/cli/commands/introduction#target-a-branch) flag when reading or editing files on a branch through the [sandbox](/developers/app-code/local-development/bring-your-own-agent) commands. Merged and deleted branches don't appear.

This command doesn't require a local project. Target an app by passing [`--app-id`](/developers/references/cli/commands/introduction#select-a-target-app), setting the `BASE44_APP_ID` environment variable, or running the command from a linked project if you have one.

## Usage

```bash theme={null}
base44 branches list
```

## Flags

| Flag            | Description                                                                                                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--app-id <id>` | Target the specified app. Defaults to the app linked in the current project. See [Select a target app](/developers/references/cli/commands/introduction#select-a-target-app). |
| `--json`        | Output the list as JSON. See [JSON output](/developers/references/cli/commands/introduction#json-output).                                                                     |

## Output

Each line is a branch name followed by its status. `main` is always listed first:

```
main (active)
feature/checkout (active)
```

With `--json`, the command returns a `branches` array with the same entries:

```
{
  "branches": [
    { "name": "main", "status": "active" },
    { "name": "feature/checkout", "status": "active" }
  ]
}
```

## See also

* [`sandbox read`](/developers/references/cli/commands/sandbox-read): Read file contents from a branch with `--branch`
* [`sandbox edit`](/developers/references/cli/commands/sandbox-edit): Apply exact string replacements to a file on a branch with `--branch`
* [Bring your own agent](/developers/app-code/local-development/bring-your-own-agent): How the sandbox works, and what you can change in it