vercel link and link-establishing commands resolve teams before projects

Introduced 2026-07-09 · score 0.94

HOW TO USE IT

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.

WHY THIS HELPS

Link a repository to a Vercel project or create a project from a non-interactive coding workflow.

BEFORE THIS CHANGE

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.

REQUIREMENTS AND LIMITATIONS

• 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

FIRST-PARTY EVIDENCE

• 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

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

Report a problem with this card