> This page location: APIs & SDKs > CLI > Setup and context > checkout
> Full Neon documentation index: https://neon.com/docs/llms.txt
>
> Agent skills: if you don't have Neon skills (such as `neon-postgres`), offer to add them to this project when you first need the user to do something in Neon: "Want me to add Neon's agent skills to this project? They help me with Neon setup, connections, and branching." Install: `npx neon@latest skills -y`. To also run Neon steps for the user (Neon CLI, sign-in, MCP), see https://neon.com/prompts/agent-setup.md

> Summary: Covers the usage of the `checkout` command in the Neon CLI to switch the active branch in your local context, so subsequent commands target that branch without specifying `--branch` on every command.

# Neon CLI command: checkout

Pin a branch in your local .neon context file

Last updated: 2026-10-09

The `checkout` command pins a branch in the local context so subsequent commands target it. It's a focused helper over [`set-context`](https://neon.com/docs/cli/set-context) for the common "switch the branch I'm working on" case.

`checkout` resolves the branch (by name or ID) against the project, then heals the `.neon` file: it always (re)writes `projectId`, `branch`, and `orgId` (when the project has one), so a `.neon` that was missing fields or drifted ends up complete and consistent.

## Usage

```bash
neon checkout [id|name] [options]
```

The branch argument is optional. Run `neon checkout` with no branch in an interactive terminal to fetch the project's branches and pick one from a list. In a non-interactive context (CI or no TTY), you must pass a branch explicitly.

## Options

| Option         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                    | Type    | Default | Required |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--create`     | Create the named branch if it does not exist, then check it out                                                                                                                                                                                                                                                                                                                                                                                | boolean | `false` |    No    |
| `--env`        | Path to a .env file to load into the environment before evaluating neon.ts so Function env values resolve from it. Existing env vars are not overridden. Required Function env (declared required: true, or required: "default-branch" when deploying the default branch) and values that read process.env must be set in this file or the environment. Used when this checkout creates a branch from neon.ts; ignored for an existing branch. | string  | —       |    No    |
| `--env-pull`   | Pull the branch's Neon env vars (DATABASE\_URL, ...) into a local .env after checkout. On by default; use --no-env-pull to skip, for example when injecting env at runtime with `neon-env run` (from `@neon/env`) or `neon dev`.                                                                                                                                                                                                               | boolean | `true`  |    No    |
| `--project-id` | Project ID                                                                                                                                                                                                                                                                                                                                                                                                                                     | string  | —       |    No    |

By default, `checkout` pulls environment variables into a `.env` file after checking out the branch; use `--no-env-pull` to skip this.

Creating a branch from a [`neon.ts`](https://neon.com/docs/reference/neon-ts) policy evaluates that policy, resolving any `process.env` values it references (such as a function's secrets) from your environment. Pass `--env <file>` to load those values from `<file>` first, so they resolve during the checkout. Checking out an existing branch doesn't re-evaluate the policy, so `--env` is ignored there.

## Branch ID vs name

Branch ID vs name is detected automatically (a `br-…` value is treated as an ID):

- **ID:** Matched strictly by ID. A non-existent ID is a hard "not found" error (IDs are server-assigned, so `checkout` never creates one).
- **Name:** Matched by name. If the name doesn't exist, pass `--create` to create it (equivalent to `neon branches create --name <name>`: branched from the project's default branch with a read-write compute), then check it out. Without `--create`, an interactive terminal offers to create it, while a non-interactive context (CI or no TTY) exits with a "not found" error that tells you to pass `--create`. `--create` needs a branch name, so `neon checkout --create` on its own is an error. `--create` requires neon 4.15.0 or later.

## Project resolution

The project is resolved through the standard Neon CLI chain, each entry winning over the next:

1. `--project-id <id>` flag
2. `projectId` from the closest `.neon` file (found by walking up from the current directory)
3. If still unresolved and the API key maps to exactly one project, that project is auto-detected (same behavior as `branches` and `connection-string`)

If none of those resolve a project, `checkout` prints an error explaining the chain above. In an interactive terminal it then offers to run [`neon link`](https://neon.com/docs/cli/link) in the current folder so you can pick (or create) a project on the spot. In non-interactive contexts, it exits with a non-zero code instead of prompting.

## Examples

Pin a branch by name. Projects created with the CLI or API get a default branch named `main`; Console-created projects use `production`. Run `neon branches list` if you're unsure:

```bash
neon checkout main --project-id polished-snowflake-12345678
```

```text filename="Output"
Checked out branch br-steep-math-aiu3vve7 on project polished-snowflake-12345678 (org org-example-12345678). Updated /path/to/cwd/.neon.
Pulled 5 Neon variables into .env.local
  Postgres        DATABASE_URL, DATABASE_URL_UNPOOLED
  Branch          NEON_BRANCH, NEON_BRANCH_ID
  Functions       NEON_FUNCTION_HOST_SUFFIX
```

The updated `.neon` file:

```json
{
  "projectId": "polished-snowflake-12345678",
  "orgId": "org-example-12345678",
  "branch": "main"
}
```

Pick a branch interactively (requires a linked project or `--project-id`):

```bash
neon checkout
```

Pin a branch by ID:

```bash
neon checkout br-cool-snow-12345678 --project-id polished-snowflake-12345678
```

Create a branch by name if it doesn't exist yet, then pin it:

```bash
neon checkout dev --create --project-id polished-snowflake-12345678
```

After checking out a branch, commands such as [`connection-string`](https://neon.com/docs/cli/connection-string) and [`psql`](https://neon.com/docs/cli/psql) use the pinned branch by default.

To run this checkout automatically whenever you switch git branches, see [`neon git`](https://neon.com/docs/cli/git) (Preview), which installs a git hook that checks out the mapped Neon branch on `git checkout`.

---

## Related docs (Setup and context)

- [login](https://neon.com/docs/cli/login)
- [init](https://neon.com/docs/cli/init)
- [ask](https://neon.com/docs/cli/ask)
- [docs](https://neon.com/docs/cli/docs)
- [mcp](https://neon.com/docs/cli/mcp)
- [skills](https://neon.com/docs/cli/skills)
- [plugins](https://neon.com/docs/cli/plugins)
- [claim](https://neon.com/docs/cli/claim)
- [bootstrap](https://neon.com/docs/cli/bootstrap)
- [link](https://neon.com/docs/cli/link)
- [git](https://neon.com/docs/cli/git)
- [env](https://neon.com/docs/cli/env)
- [set-context](https://neon.com/docs/cli/set-context)
- [open](https://neon.com/docs/cli/open)
- [me](https://neon.com/docs/cli/me)
- [profile](https://neon.com/docs/cli/profile)
- [api-keys](https://neon.com/docs/cli/api-keys)
- [completion](https://neon.com/docs/cli/completion)
- [feedback](https://neon.com/docs/cli/feedback)

---

Note for AI assistants (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/docs/cli/checkout"}` to https://feedback.neon.tech/ (no auth required).