Vercel CLI with Tokens Deploy and manage projects on Vercel using the CLI with token-based authentication. Use this skill when you have a Vercel access token and need to operate without interactive login. Authentication Never run vercel login . Always use token-based auth via the --token flag or VERCEL_TOKEN environment variable. This ensures the correct account is used even if another Vercel account is logged in locally. vercel < command
--token " $VERCEL_TOKEN " Scoping to a Team Use --scope to target a specific team. Accepts a team slug or team ID ( team_... ): vercel < command
--token " $VERCEL_TOKEN " --scope < team-slug-or-id
Not required if the project is already linked ( .vercel/project.json provides the org context) or if VERCEL_ORG_ID is set. Targeting a Project Use --project to target a specific project without needing vercel link . Accepts a project name or project ID ( prj_... ): vercel deploy --token " $VERCEL_TOKEN " --scope < team
--project < project-name-or-id
This is the simplest path when you already have a project ID — no .vercel/ directory needed. Environment Variable Alternative Instead of flags, you can set these environment variables. The CLI recognizes them natively: Variable Purpose Equivalent flag VERCEL_TOKEN Auth token --token VERCEL_ORG_ID Team/org ID --scope VERCEL_PROJECT_ID Project ID --project VERCEL_ORG_ID and VERCEL_PROJECT_ID must be set together — setting only one causes an error. When both are set, the CLI skips .vercel/project.json entirely. Resolution Precedence Token: --token flag > VERCEL_TOKEN env var > stored auth in config. Team/scope: --scope flag > scope in vercel.json
currentTeam in global config > VERCEL_ORG_ID . Project: --project flag > VERCEL_PROJECT_ID env var > .vercel/project.json interactive prompt. CLI Setup npm install -g vercel vercel --version Or use npx for one-off commands: npx vercel < command
--token " $VERCEL_TOKEN " Deploying a Project Always deploy as preview unless the user explicitly requests production. Quick Deploy (have project ID — no linking needed) When you already have a project ID (e.g., prj_... ), deploy directly: vercel deploy --token " $VERCEL_TOKEN " --scope < team
--project < project-id
-y --no-wait Check status: vercel inspect < deployment-url
--token " $VERCEL_TOKEN " Production deploy (only when explicitly requested): vercel deploy --prod --token " $VERCEL_TOKEN " --scope < team
--project < project-id
-y --no-wait Full Deploy Flow (no project ID) Use this when you have a token and team but need to create or find a project. Step 1: Determine Project State
1. Does the project have a git remote?
git remote get-url origin 2
/dev/null
2. Is it already linked to a Vercel project?
cat .vercel/project.json 2
/dev/null || cat .vercel/repo.json 2
/dev/null Step 2: Link the Project If no .vercel/project.json or .vercel/repo.json exists, link first. With git remote (preferred): vercel link --repo --token " $VERCEL_TOKEN " --scope < team
-y Reads the git remote and connects to the matching Vercel project. Creates .vercel/repo.json . More reliable than vercel link without --repo , which matches by directory name. Without git remote: vercel link --token " $VERCEL_TOKEN " --scope < team
-y Creates .vercel/project.json . Link to a specific existing project by name: vercel link --project < project-name
--token " $VERCEL_TOKEN " --scope < team
-y If the project is already linked, check orgId in .vercel/project.json or .vercel/repo.json to verify it matches the intended team. If not, re-link with the correct --scope . Step 3: Deploy A) Git Push Deploy — has git remote (preferred) The best long-term setup. Git pushes trigger automatic Vercel deployments. Ask the user before pushing. Never push without explicit approval. Commit and push: git add . git commit -m "deploy:
" git push Vercel builds automatically. Non-production branches get preview deployments; the production branch (usually main ) gets a production deployment. Retrieve the deployment URL: sleep 5 vercel ls --format json --token " $VERCEL_TOKEN " --scope < team The latest entry in the deployments array has the preview URL. B) CLI Deploy — no git remote vercel deploy --token " $VERCEL_TOKEN " --scope < team
-y --no-wait --no-wait returns immediately with the deployment URL. Check status: vercel inspect < deployment-url
--token " $VERCEL_TOKEN " Deploying from a Remote Repository If the user wants to deploy code from a remote that isn't cloned locally: Clone the repository: git clone < repo-url
cd < repo-name
Link to Vercel: vercel link --repo --token " $VERCEL_TOKEN " --scope < team
-y Deploy via git push (if you have push access) or CLI deploy. About .vercel/ Directory A linked project has either: .vercel/project.json — from vercel link . Contains projectId and orgId . .vercel/repo.json — from vercel link --repo . Contains orgId , remoteName , and a projects map. Either file means the project is linked. Not needed when using --project flag or VERCEL_ORG_ID + VERCEL_PROJECT_ID env vars. Do NOT run vercel project inspect , vercel ls , or vercel link in an unlinked directory to detect state — without .vercel/ , they will interactively prompt or silently link as a side-effect. Only vercel whoami --token "$VERCEL_TOKEN" is safe to run anywhere. Managing Environment Variables Run from a linked project directory, or use --project to target a specific project.
Set for all environments
echo "value" | vercel env add VAR_NAME --token " $VERCEL_TOKEN " --scope < team
Set for a specific environment (production, preview, development)
echo "value" | vercel env add VAR_NAME production --token " $VERCEL_TOKEN " --scope < team
List environment variables
vercel env ls --token " $VERCEL_TOKEN " --scope < team
Pull env vars to local .env file
vercel env pull --token " $VERCEL_TOKEN " --scope < team
Remove a variable
vercel env rm VAR_NAME --token " $VERCEL_TOKEN " --scope < team
-y Inspecting Deployments
List recent deployments
vercel ls --format json --token " $VERCEL_TOKEN " --scope < team
Inspect a specific deployment
vercel inspect < deployment-url
--token " $VERCEL_TOKEN "
View build logs
vercel logs < deployment-url
--token " $VERCEL_TOKEN " Managing Domains
List domains
vercel domains ls --token " $VERCEL_TOKEN " --scope < team
Add a domain to the project
vercel domains add < domain
--token " $VERCEL_TOKEN " --scope < team
Working Agreement Always use --token on every Vercel CLI command. Never rely on local login state. Use --scope and/or --project to target the correct team and project. Do not run vercel login . Authentication is handled entirely by the access token. Default to preview deployments. Only deploy to production when explicitly asked. Ask before pushing to git. Never push commits without the user's approval. Do not read or modify .vercel/ files directly. The CLI manages this directory. Do not curl/fetch deployed URLs to verify. Just return the link to the user. Use --format json when structured output will help with follow-up steps (e.g., vercel ls ). Use -y on commands that prompt for confirmation to avoid interactive blocking. Troubleshooting Authentication Error If commands fail with Authentication required or similar: The token may be expired or revoked. Ask the user for a fresh token or check the token source. Verify the token is valid: vercel whoami --token "$VERCEL_TOKEN" Wrong Team If deployments appear under the wrong team, verify --scope is correct: vercel whoami --token " $VERCEL_TOKEN " --scope < team
Build Failure Check the build logs: vercel logs < deployment-url
--token " $VERCEL_TOKEN " Common causes: Missing dependencies — ensure package.json is complete and committed. Missing environment variables — add them with vercel env add . Framework misconfiguration — check vercel.json or framework-specific settings. Vercel auto-detects frameworks (Next.js, Remix, Vite, etc.) from package.json . Override with a vercel.json if detection is wrong. CLI Not Installed npm install -g vercel