Skip to content
Docs

vercel link

The vercel link command links your local directory to a Vercel Project.

terminal
vercel link

Using the vercel link command to link the current directory to a Vercel Project.

terminal
vercel link --cwd [path-to-directory]

Using the vercel link command and supplying a path to the local directory of the Vercel Project.

Use vercel link add to add projects to an existing repository link while preserving its current project mappings. Run vercel link --repo first to create .vercel/repo.json at the repository root. The repository must have a Git remote, and existing Vercel Projects must connect to that remote through the Git integration.

terminal
vercel link add
Adding projects to an existing repository link.

The command uses the Git remote saved in .vercel/repo.json and prompts you to choose a team and projects. It excludes projects whose ID or root directory already appears in the repository link. Interactive selection can also offer to create projects for detected local applications. Selecting those entries creates Vercel Projects and connects them to the Git repository.

After you select projects, the command appends their mappings to .vercel/repo.json. You can run vercel link add from the repository root or a subdirectory. If no eligible projects remain, the existing repository link stays unchanged.

To add all eligible existing projects without answering prompts, use --yes (or -y):

terminal
vercel link add --yes --scope your_team_slug
Adding existing projects from a specific team without prompts.

With --yes, the command selects existing projects and skips creating detected local applications. For non-interactive usage, provide --scope explicitly and authenticate with a token or existing login.

These are options that only apply to the vercel link command.

The --repo option can be used to link all projects in your repository to their respective Vercel projects in one command. This command requires that your Vercel projects are using the Git integration.

terminal
vercel link --repo
Using the vercel link command with the --repo option.

The --yes option can be used to skip questions you are asked when setting up a new Vercel Project. The CLI answers the questions with the current directory for the Vercel Project name and location. The --yes option does not choose a team. If you belong to more than one team, also pass the --scope option.

terminal
vercel link --yes

Using the vercel link command with the --yes option.

The --project option specifies a project name or ID. In non-interactive usage, --project allows you to set a project that does not match the name of the current working directory.

terminal
vercel link --yes --project foo

Using the vercel link command with the --project option.

To use a project without a link, for example in a CI/CD pipeline, set both the VERCEL_ORG_ID and VERCEL_PROJECT_ID environment variables. Vercel CLI commands then use that project, and you do not need to run vercel link. If you run vercel link with both variables set, it confirms that project without prompts, and it does not create or change the link in the .vercel directory. See CLI Global Options for how other commands select a project.

The following global options can be passed when using the vercel link command:

For more information on global options and their usage, refer to the options section.

Last updated August 11, 2026

Was this helpful?

supported.