vercel link and vercel build: Prebuilt CI Deploys
vercel link writes .vercel/project.json tying the folder to a project, and vercel build runs the build locally into .vercel/output for a prebuilt deploy.
Linking is what lets later commands know which project they act on. In CI you usually skip link entirely by exporting the org and project IDs, then build and deploy the output.
What it does
vercel link records the org and project IDs in .vercel/project.json. vercel build runs the project build the same way Vercel would, emitting a portable .vercel/output directory that vercel deploy --prebuilt can ship without rebuilding on Vercel.
Common usage
# link non-interactively to a known project
vercel link --yes --project my-app --token "$VERCEL_TOKEN"
# or skip link entirely with env vars, then build + deploy
export VERCEL_ORG_ID=team_xxx VERCEL_PROJECT_ID=prj_xxx
vercel build --prod --token "$VERCEL_TOKEN"
vercel deploy --prebuilt --prod --token "$VERCEL_TOKEN" --yesOptions
| Flag | What it does |
|---|---|
| link --yes | Link without prompting (uses defaults) |
| link --project <name> | Link to a named project |
| build --prod | Build with production env and settings |
| VERCEL_ORG_ID / VERCEL_PROJECT_ID | Env vars that replace link in CI |
| --token <t> | Token auth |
In CI
The cleanest pattern is to commit .vercel/project.json (it holds no secrets) or export VERCEL_ORG_ID and VERCEL_PROJECT_ID, then run vercel build followed by vercel deploy --prebuilt. That keeps the heavy build on the runner and the deploy fast.
Common errors in CI
"Error: Project not found" from link means the --project name or the IDs are wrong for that token's scope. "Error: The provided path does not exist" from build means you ran it outside the project root. "Your codebase isn't linked to a project" later means link did not run and the env vars are unset.