{
  "slug": "neonctl-link-and-checkout-select-a-branch-and-pull-its-environment-6263c05d5965",
  "title": "neonctl link and checkout select a branch and pull its environment",
  "tools": [
    "neonctl"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-06-10T10:23:58.000Z",
  "announced_at": "2026-06-10T10:23:58.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "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.",
    "examples": [
      "neonctl link",
      "neonctl checkout <branch> --project-id <project_id>",
      "neonctl env pull --branch <id|name> --file <path>"
    ],
    "gotchas": [
      "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."
    ]
  },
  "why_it_matters": "Link a project or switch its branch and prepare its Neon environment for local development.",
  "before": "After linking or checking out a branch, run `env pull` separately to write the branch’s Neon environment variables to a local dotenv file.",
  "sources": [
    "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"
  ],
  "rank": 0.97057,
  "judge": {
    "publish": true,
    "judge_model": "codex-cli/gpt-6-luna+typesafe/jev-1.13.0",
    "prompt_version": "extract-v7+enrich-v2+judge-v2x3+jev-publish-v1"
  },
  "review_state": "approved",
  "provenance": {
    "run_id": "wave2a-20261017",
    "verdict_id": "wave2a-20261017:wave2a-20261017-56ee09c95cc6ac4e-1:gate",
    "evidence_hash": "100ffd556d087c1cb6b299328114f7dc68808d99fddb651436480981d1b299e2"
  },
  "review": {
    "draft_hash": "1277bc3b37cc6ef86d9962fe786a2e369444f86f720cec07fa97f997a55c278f",
    "reviewer": "publication-gate",
    "reviewed_at": "2026-10-07T00:00:00.000Z",
    "decision": "wave2a-20261017:gate",
    "reason": "3 of 3 judge runs approved with p_yes >= 0.9 (mean 0.97 >= 0.9; 2 needed) and Jev gave 0.79 (>= 0.6 needed)."
  }
}