{
  "slug": "vercel-link-and-link-establishing-commands-resolve-teams-before-projects-dfae1821265c",
  "title": "vercel link and link-establishing commands resolve teams before projects",
  "tools": [
    "vercel"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-07-09T18:17:42.000Z",
  "announced_at": "2026-07-09T18:17:42.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "For non-interactive linking, provide a team signal with `--scope` or `--team`, `vercel.json` `scope`, or `VERCEL_ORG_ID`; otherwise, with multiple available teams, handle `action_required: missing_scope`. Resolve the team first, then link an existing project or create one within that team; use an explicit project name or ID to skip suggestions.",
    "examples": [
      "vercel link --scope <team-slug> --project <project-name-or-id>",
      "vercel link --scope <team-slug> --yes",
      "VERCEL_ORG_ID=<team-id> VERCEL_PROJECT_ID=<project-id> vercel link"
    ],
    "gotchas": [
      "Version: 55.0.0",
      "--scope <team-slug-or-id>: Select the team scope. For non-interactive linking, provide this or another team signal.",
      "--team <team-slug-or-id>: Team signal accepted by v55.0.0; the current global-options docs describe `--team` as specifying a team slug or ID.",
      "vercel.json `scope`: Team signal for link resolution.",
      "VERCEL_ORG_ID: Team signal; together with `VERCEL_PROJECT_ID`, identifies the explicit owner-project pair for `vercel link`.",
      "VERCEL_PROJECT_ID: Project ID; paired with `VERCEL_ORG_ID`, resolves the project-owner pair for `vercel link`.",
      "--project <name-or-id>: Select a project directly within the resolved team; skips project suggestions.",
      "--name <project-name>: Explicit project name that resolves directly within the team and skips suggestions.",
      "vercel.json `name`: Explicit project name that resolves directly within the team and skips suggestions.",
      "--yes: Answer confirmation prompts; does not choose a team. With the `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` pair, it is unnecessary.",
      "Prerequisite: Authenticate to Vercel and have access to the target team and project.",
      "Prerequisite: Without a TTY or in non-interactive mode, provide a team signal or have exactly one available team; otherwise linking fails with `action_required: missing_scope` before project discovery or project creation.",
      "Non-interactive team resolution uses an explicit signal or a single available team; otherwise the command fails with `action_required: missing_scope` before project discovery, project creation, or deletion of `.vercel/project.json`.",
      "Project discovery queries only the resolved team; the cross-team project sweep and SSO fallback prompt are removed.",
      "An explicit team signal skips the team prompt; an explicit project name skips suggestions.",
      "The `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` pair behavior applies to `vercel link`; an unresolvable pair errors instead of falling back to prompts.",
      "A single Git-linked root-directory match still links automatically.",
      "Docs conflict: The `vercel link` documentation says `--yes` answers setup questions using the default scope. That conflicts with v55.0.0: `--yes` does not select a team. https://vercel.com/docs/cli/link"
    ]
  },
  "why_it_matters": "Link a repository to a Vercel project or create a project from a non-interactive coding workflow.",
  "before": "Without a TTY, `vercel link` could fall back to the globally selected team from `vc switch` or the login default; `--yes` could silently use that team. Project discovery could sweep across teams and prompt for SSO fallback.",
  "sources": [
    "https://github.com/vercel/vercel/releases/tag/vercel%4055.0.0",
    "https://vercel.com/docs/cli/link",
    "https://github.com/vercel/vercel/releases/tag/vercel@55.0.0",
    "https://vercel.com/docs/cli/global-options"
  ],
  "rank": 0.9406,
  "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": "backfill-20261007",
    "verdict_id": "backfill-20261007:backfill-20261007-2469f5aeef7006ad-0:gate",
    "evidence_hash": "ddf693a4af6748affb97cec548645044518407accdbfd723c075d3f92707c791"
  },
  "review": {
    "draft_hash": "444403809be77ec2523e995ddc12245b538b3a8fd09fd964fe27375536e79505",
    "reviewer": "publication-gate",
    "reviewed_at": "2026-10-07T00:00:00.000Z",
    "decision": "backfill-20261007:gate",
    "reason": "3 of 3 judge runs approved with p_yes >= 0.9 (mean 0.94 >= 0.9; 2 needed) and Jev gave 0.76 (>= 0.6 needed)."
  }
}