neonctl link and checkout select a branch and pull its environment

Introduced 2026-06-10 · score 0.97

HOW TO USE IT

When linking an existing project with multiple branches, run `neonctl link` and select a branch; single-branch projects are pinned automatically. After `link` or `checkout` pins a branch, it pulls Neon environment variables by default; pass `--no-env-pull` to skip the pull, or run `neonctl env pull` to refresh them.

WHY THIS HELPS

Link a project or switch its branch and prepare its Neon environment for local development.

BEFORE THIS CHANGE

After linking or checking out a branch, run `env pull` separately to write the branch’s Neon environment variables to a local dotenv file.

REQUIREMENTS AND LIMITATIONS

• Version: v2.24.1
• --no-env-pull: Skip the automatic environment pull after `link` or `checkout`.
• <branch>: For `checkout`, the branch name or ID to pin. Omit in an interactive terminal to choose from a list; required in non-interactive contexts.
• --project-id <id>: Select the project for `checkout`; otherwise context or project auto-detection may resolve it.
• --branch <id|name>: For `env pull`, target a branch other than the one in the closest `.neon` context file.
• --file <path>: Choose the dotenv file for `env pull`; default is existing `.env`, otherwise `.env.local`.
• Prerequisite: Authenticate with `neonctl auth`, or provide an API key with `--api-key`; unauthenticated CLI commands launch browser authentication automatically.
• Prerequisite: `neonctl link` requires the CLI to resolve or be given an organization and project; `checkout` requires a resolvable project.
• The selector is for linking an existing project with more than one branch; a single-branch project is pinned automatically.
• New projects pin their default branch.
• Non-interactive/flag mode and the `--agent` state machine are unchanged.
• Only Neon-managed keys are written; any other lines in the dotenv file are preserved.
• An existing `.env` is used when present, otherwise `.env.local`; `--file <path>` overrides the target file.
• The branch comes from the closest `.neon` file unless `--branch <id|name>` targets another branch.
• A pull failure does not undo the checkout; it is surfaced as a warning.

FIRST-PARTY EVIDENCE

• https://github.com/neondatabase/neonctl/releases/tag/v2.24.1
• https://github.com/neondatabase/neonctl/pull/524
• https://github.com/neondatabase/neonctl/blob/v2.24.1/README.md

Check the installed version and the source before using it. Entry JSON

Report a problem with this card