Skip to main content
See what's recently landed on the Neon backend: Object Storage, Functions, AI Gateway, and more
/APIs & SDKs/Setup and context/checkout

Neon CLI command: checkout

Pin a branch in your local .neon context file

View as Markdown

The checkout command pins a branch in the local context so subsequent commands target it. It's a focused helper over 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

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

OptionDescriptionTypeDefaultRequired
--createCreate the named branch if it does not exist, then check it outbooleanfalseNo
--envPath 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-pullPull 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.booleantrueNo
--project-idProject IDstring—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 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 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:

neon checkout main --project-id polished-snowflake-12345678
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:

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

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

neon checkout

Pin a branch by ID:

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:

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

After checking out a branch, commands such as connection-string and psql use the pinned branch by default.

To run this checkout automatically whenever you switch git branches, see neon git (Preview), which installs a git hook that checks out the mapped Neon branch on git checkout.

Last updated on

Was this page helpful?
Edit on GitHub