{
  "slug": "neonctl-link-binds-a-directory-to-a-neon-project-329a57f36bfb",
  "title": "neonctl link binds a directory to a Neon project",
  "tools": [
    "neonctl"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-06-04T13:28:49.000Z",
  "announced_at": "2026-06-04T13:28:49.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "When you need subsequent `neonctl` commands in a directory or its subdirectories to use a Neon project context, run `neonctl link` there. Use interactive prompts, the documented flags or `--params` for scripts, or `--agent` for the JSON follow-up flow; the command writes `.neon` with organization, project, and default branch context.",
    "examples": [
      "neonctl link",
      "neonctl link --org-id <org-id> --project-id <project-id>",
      "neonctl link --params '{\"orgId\":\"<org-id>\",\"projectName\":\"<project-name>\",\"regionId\":\"<region-id>\"}'"
    ],
    "gotchas": [
      "Version: v2.22.2",
      "--org-id: Organization ID; used to choose the organization for linking or project creation.",
      "--project-id: Existing project ID to link.",
      "--project-name: Name for a project to create and link.",
      "--region-id: Region ID for the project being created; the agent flow can omit it to receive available regions.",
      "--params: JSON payload form of the linking parameters; documented keys are `orgId`, `projectName`, and `regionId`.",
      "--agent: Returns a JSON state-machine response with status, available options, and a follow-up command template.",
      "Prerequisite: Install neonctl; the v2.22.2 README specifies Node.js 18.0 or higher for the npm installation.",
      "Prerequisite: Authenticate with `neonctl auth` or provide a Neon API key with `--api-key` when running a CLI command.",
      "Interactive mode is the default.",
      "Non-interactive linking uses flags or `--params` JSON.",
      "Agent mode returns a JSON object with a status discriminator, available options, and a follow-up command."
    ]
  },
  "why_it_matters": "Link a repository directory to a Neon project so subsequent CLI commands can use that directory’s project context.",
  "before": "Use the lower-level `neonctl set-context` command to write project context manually; `link` is documented as a wrapper around that primitive.",
  "sources": [
    "https://github.com/neondatabase/neonctl/releases/tag/v2.22.2",
    "https://github.com/neondatabase/neonctl/pull/473",
    "https://github.com/neondatabase/neonctl/blob/v2.22.2/README.md"
  ],
  "rank": 0.98064,
  "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-36c2bc321495e539-2:gate",
    "evidence_hash": "54af7d3b6f9046345b81475124f92065ccd208bf51a027b6f5c4c0710c9c5c4f"
  },
  "review": {
    "draft_hash": "7028c55c947e26918b747ec58cb2ee264114cfab328fb48d49c50d665d236e61",
    "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.98 >= 0.9; 2 needed) and Jev gave 0.81 (>= 0.6 needed)."
  }
}