Vercel CLI com Tokens

Implante e gerencie projetos na Vercel usando a CLI com autenticação baseada em token, sem depender de vercel login.

Quando Usar

• Use esta habilidade quando a tarefa corresponder a esta descrição: Implante e gerencie projetos na Vercel usando autenticação baseada em token. Use ao trabalhar com a Vercel CLI usando tokens de acesso em vez de login interativo — por exemplo, "implantar na vercel", "configurar vercel", "adicionar variáveis de ambiente à vercel".

Passo 1: Localize o Token da Vercel

Antes de executar quaisquer comandos da Vercel CLI, identifique de onde o token está vindo. Trabalhe com esses cenários em ordem:

A) VERCEL_TOKEN já está definido no ambiente

[ -n "${VERCEL_TOKEN:-}" ] && printf 'VERCEL_TOKEN is set\n'

Se isso relatar um token configurado, você está pronto. Pule para o Passo 2.

B) O token está em um arquivo .env sob VERCEL_TOKEN

grep -q '^VERCEL_TOKEN=' .env 2>/dev/null && printf 'VERCEL_TOKEN is present in .env\n'

Se encontrado, exporte-o:

VERCEL_TOKEN="$(sed -n 's/^VERCEL_TOKEN=//p' .env | tail -n 1)"
export VERCEL_TOKEN

C) O token está em um arquivo .env sob um nome diferente

Procure por qualquer variável que pareça um token da Vercel (tokens da Vercel geralmente começam com vca_):

grep -Eio '^[A-Z0-9_]*VERCEL[A-Z0-9_]*(?==)' .env 2>/dev/null

Inspecione a saída para identificar qual variável contém o token e, em seguida, exporte-o como VERCEL_TOKEN:

vercel_var="<VARIABLE_NAME>"
VERCEL_TOKEN="$(sed -n "s/^${vercel_var}=//p" .env | tail -n 1)"
export VERCEL_TOKEN

D) Nenhum token encontrado — pergunte ao usuário

Se nenhuma das opções acima fornecer um token, peça ao usuário para fornecê-lo. Eles podem criar um token de acesso da Vercel em vercel.com/account/tokens.

Importante: Uma vez que VERCEL_TOKEN é exportado como uma variável de ambiente, a Vercel CLI o lê nativamente — não o passe como um flag --token. Colocar segredos em argumentos de linha de comando os expõe no histórico do shell e nas listagens de processos.

# Bad — token visible in shell history and process listings
vercel deploy --token "vca_abc123"

# Good — CLI reads VERCEL_TOKEN from the environment
[ -n "${VERCEL_TOKEN:-}" ] || { echo "Set VERCEL_TOKEN first" >&2; exit 1; }
vercel deploy

Passo 2: Localize o Projeto e a Equipe

Da mesma forma, verifique o ID do projeto e o escopo da equipe. Isso permite que a CLI direcione o projeto certo sem precisar de vercel link.

# Check environment
[ -n "${VERCEL_PROJECT_ID:-}" ] && printf 'VERCEL_PROJECT_ID is set\n'
[ -n "${VERCEL_ORG_ID:-}" ] && printf 'VERCEL_ORG_ID is set\n'

# Or check .env
grep -Eio '^[A-Z0-9_]*VERCEL[A-Z0-9_]*(?==)' .env 2>/dev/null

Se você tiver uma URL de projeto (por exemplo, https://vercel.com/my-team/my-project), extraia o slug da equipe:

# e.g. "my-team" from "https://vercel.com/my-team/my-project"
echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1

Se você tiver VERCEL_ORG_ID e VERCEL_PROJECT_ID no seu ambiente, exporte-os — a CLI os usará automaticamente e ignorará qualquer diretório .vercel/:

export VERCEL_ORG_ID="<org-id>"
export VERCEL_PROJECT_ID="<project-id>"

Nota: VERCEL_ORG_ID e VERCEL_PROJECT_ID devem ser definidos juntos — definir apenas um causa um erro.

Configuração da CLI

Certifique-se de que a Vercel CLI esteja instalada e atualizada:

npm install -g vercel
vercel --version

Implantando um Projeto

Sempre implante como preview, a menos que o usuário solicite explicitamente produção. Escolha um método com base no que você tem disponível.

Implantação Rápida (tem ID do projeto — sem necessidade de vinculação)

Quando VERCEL_TOKEN e VERCEL_PROJECT_ID estiverem definidos no ambiente, implante diretamente:

vercel deploy -y --no-wait

Com um escopo de equipe (via VERCEL_ORG_ID ou --scope):

vercel deploy --scope <team-slug> -y --no-wait

Produção (somente quando explicitamente solicitado):

vercel deploy --prod --scope <team-slug> -y --no-wait

Verificar status:

vercel inspect <deployment-url>

Fluxo de Implantação Completo (sem ID do projeto — precisa vincular)

Use isso quando você tiver um token e uma equipe, mas nenhum ID de projeto preexistente.

Verifique o estado do projeto primeiro

# Does the project have a git remote?
git remote get-url origin 2>/dev/null

# Is it already linked to a Vercel project?
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

Vincule o projeto

Com remote git (preferencial):

vercel link --repo --scope <team-slug> -y

…