{"slug": "a-branch-first-dev-loop-for-neon-link-checkout-and-env-pull", "title": "A branch-first dev loop for Neon: link, checkout and env pull", "summary": "Neon released three new CLI commands — `neonctl link`, `neonctl checkout`, and `neonctl env pull` — to streamline branch-first development workflows for its serverless Postgres platform. The commands allow developers to link a local workspace to a Neon project, switch between database branches, and automatically pull branch-specific environment variables, eliminating manual configuration steps. The update aims to make isolated development environments the default for both human developers and coding agents.", "body_md": "We're hard at work shipping the private preview of [Neon Platform](https://neon.com/blog/were-building-backends) and while we're at it we're rethinking Neon's developer experience from the ground up. A lot of that work is about making branch-first development the default, not something you have to wire up yourself.\n\nThe first piece is shipping today: three new Neon CLI commands that make branch-first development easier than ever. `neonctl link`\n\n, `neonctl checkout`\n\nand `neonctl env pull`\n\n. They benefit you whether you only use Neon Serverless Postgres or you're reaching for more of the Neon Platform going forward. And they're especially useful once you hand the feature-dev loop to a coding agent.\n\n## Link your workspace to a Neon project\n\n`neonctl link`\n\nconnects your local dev workspace to a Neon project, the same way `vercel link`\n\ndoes for your Vercel project.\n\nIt's interactive: pick a Neon org, pick or create a project and branch, then the CLI writes the org, project and branch IDs into a local `.neon`\n\nfile. That file is git-ignored by default, so it stays a per-developer pointer.\n\nAnd for agents that don't do interactive mode, there's `neonctl link --agent`\n\n.\n\nIf you're a long-time `neonctl`\n\nuser, you'll know this was already possible through the lower-level `set-context`\n\ncommand. `link`\n\nis just an interactive wrapper on top of the lower-level primitive.\n\nOnce a workspace is linked, project- and branch-scoped commands stop needing `--project-id`\n\nand `--branch`\n\nflags. For example, this lists every branch in the linked project, no arguments required:\n\nThat's convenient on its own. It becomes a game-changer once you add `env pull`\n\n.\n\n## Pull branch-scoped env vars with env pull\n\n`neonctl env pull`\n\nfetches the current branch's Neon environment variables into your existing `.env`\n\nfile, or `.env.local`\n\nif you don't have one. You can also point it at any file with `--file`\n\n.\n\nIt pulls the env variables based on your current branch's enabled services. You always get `DATABASE_URL`\n\nand `DATABASE_URL_UNPOOLED`\n\n(the pooled and direct Postgres connection strings), plus the Neon Auth and Data API secrets when those services are enabled on the branch. And as our preview features roll out (object storage and an AI gateway) you'll get those too if you're using them. Only the Neon-managed keys are written, so everything else in your file is left untouched.\n\nThere's no branch ID to pass, because it's already in `.neon`\n\n. Giving your teammates, both human and agent, an isolated Neon branch for development is great. Pulling all the branch-scoped connection details for that branch by hand is the annoying part. `env pull`\n\nis the fix.\n\nIn fact, you'll rarely run `env pull`\n\nyourself: as you'll see below, `link`\n\nand `checkout`\n\nrun it for you, so pinning a branch and pulling its env are a single step.\n\n## Switch branches with checkout\n\nThe last ingredient is switching branches. Neon brings git-like branching to Postgres (and soon the full suite of Neon backend primitives), so inspired by git again, we added a quick utility command for it: `checkout`\n\n.\n\n`neonctl checkout <branch-name>`\n\nlets you create a branch or check out an existing one. Run it without a name and you get an interactive branch picker with a create option:\n\nCheckout updates the branch identifier in your `.neon`\n\nfile so the next CLI commands target that branch.\n\n## The branch-first dev loop\n\nPut them together and branching has never been easier to integrate tightly into your everyday dev workflow. Run `neonctl link`\n\nonce when you start on a project:\n\nThen run `neonctl checkout`\n\nwhenever you'd reach for `git checkout -b`\n\n, at the start of every feature, fix or experiment, to give that work its own isolated Neon branch:\n\nAnd as I mentioned earlier, `neonctl env pull`\n\nalready runs under the hood for both `link`\n\nand `checkout`\n\n, so your `.env`\n\n(or `.env.local`\n\n) already holds the right Neon environment variables for the branch you just checked out. Your app always points at the branch you're actually working on and nothing leaks between features.\n\nYou can still run `neonctl env pull`\n\ndirectly to refresh a branch's env or pull a different branch into a specific file with `--file`\n\n.\n\n## Hand these commands to your agent\n\nBranching is great for devs but essential for agents (I make a ton of mistakes but my agents even more so). An agent can run `neonctl checkout`\n\nbetween tasks to give itself a fresh, isolated database per feature with no shared state to corrupt and no connection strings to copy around.\n\nI'd add a small paragraph to my own `AGENTS.md`\n\n(and `CLAUDE.md`\n\n) so my agents pick up the loop by default. Something like:\n\nOn top of that, install the new `neon`\n\nagent skill. It teaches your agent the full branch-first dev workflow with Neon plus other Neon Platform best practices:\n\nThen prompt your agent to do branch-first feature development and let it drive the loop.\n\n## What if you don't want env vars on disk?\n\nWriting secrets into a local `.env`\n\nis the right default for most local dev. I bet you have a bunch of `.env`\n\nfiles on your machine even though you post about using [varlock](https://varlock.dev) on X! However, `neonctl env pull`\n\nis optional. You can opt out and we give you alternative ways to inject your Neon env variables for local dev.\n\nFirst, pass `--no-env-pull`\n\nto opt out of the bundled pull:\n\n### Inject it at runtime\n\nOur new `@neondatabase/env`\n\npackage gives you a few ways to inject your branch's env at runtime instead of writing it to disk:\n\n`neon-env run`\n\nto inject env into your dev command`fetchEnv`\n\nto resolve env in code`neonctl dev`\n\n(coming soon) for Neon Functions\n\n`neon-env run`\n\nfetches your branch's Neon variables and injects them into the child process, so nothing is written to disk:\n\n`fetchEnv`\n\ndoes the same in code. Pass it your `neon.ts`\n\nconfig and the branch to resolve and it hands you back a typed env object you can read at your app's bootstrap:\n\n`neonctl dev`\n\nis coming soon for Neon Functions. It runs your local dev server with that same branch env injected, so the branch-first loop carries straight over to Neon Functions development:\n\n### Pull it into your env manager\n\nAnd if you're actually using varlock, `@neondatabase/env`\n\nalso ships a `neon-env export`\n\ncommand that prints your branch's env to stdout as dotenv lines or JSON. You can pull Neon straight into a varlock `.env.schema`\n\nwith a bulk loader:\n\nNow varlock resolves your Neon branch's `DATABASE_URL`\n\n(and friends) on demand and you still get varlock's schema validation and secret redaction on top.\n\n### Make it stick\n\nTo make sure you never forget the flag, wrap the commands in your `package.json`\n\nscripts:\n\nAnd for your agents, add a line to your `AGENTS.md`\n\nso they follow the same rule. For example: *\"Use neonctl checkout <branch> --no-env-pull and never run neonctl env pull; env is injected at runtime via neon-env run.\"*\n\n## Wrapping up\n\nOur agents ship feature after feature (or even in parallel). Branching is key to isolating your infra per feature. Our goal is to give you the best primitives for branch-first development: use them as documented here or make them your own and build your own abstractions on top!\n\nThis is the first of several DX improvements landing as we build toward the Neon Platform private preview, with more CLI commands and new SDKs on the way. If there's something you wish the Neon CLI did, drop into the [Neon Discord](https://discord.gg/tXC49r2M4q) and tell us.\n\nAnd if the little Neon Platform teasers got you interested, sign up for the private preview [here](https://neon.com/blog/were-building-backends#access).\n\nHappy coding!", "url": "https://wpnews.pro/news/a-branch-first-dev-loop-for-neon-link-checkout-and-env-pull", "canonical_source": "https://neon.com/blog/branch-first-dev-loop", "published_at": "2026-06-10 12:00:00+00:00", "updated_at": "2026-06-11 17:36:44.729220+00:00", "lang": "en", "topics": ["ai-tools", "ai-infrastructure", "ai-products", "ai-startups", "mlops"], "entities": ["Neon", "Neon Platform", "Neon Serverless Postgres", "Vercel", "neonctl"], "alternates": {"html": "https://wpnews.pro/news/a-branch-first-dev-loop-for-neon-link-checkout-and-env-pull", "markdown": "https://wpnews.pro/news/a-branch-first-dev-loop-for-neon-link-checkout-and-env-pull.md", "text": "https://wpnews.pro/news/a-branch-first-dev-loop-for-neon-link-checkout-and-env-pull.txt", "jsonld": "https://wpnews.pro/news/a-branch-first-dev-loop-for-neon-link-checkout-and-env-pull.jsonld"}}