Vercel CLI com Tokens

O que Vercel CLI com Tokens faz?

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

Passo 1: Localizar o Token da Vercel

Antes de executar qualquer comando do Vercel CLI, identifique de onde o token está vindo. Percorra estes cenários em ordem:

A) VERCEL_TOKEN já está definido no ambiente

printenv VERCEL_TOKEN

Se isso retornar um valor, você está pronto. Pule para o Passo 2.

B) Token está em um arquivo .env com VERCEL_TOKEN

grep '^VERCEL_TOKEN=' .env 2>/dev/null

Se encontrado, exporte:

export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)

C) Token está em um arquivo .env com nome diferente

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

grep -i 'vercel' .env 2>/dev/null

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

export VERCEL_TOKEN=$(grep '^<NOME_DA_VARIAVEL>=' .env | cut -d= -f2-)

D) Nenhum token encontrado — pergunte ao usuário

Se nenhum dos acima fornecer um token, peça ao usuário para fornecer um. Eles podem criar um token de acesso da Vercel em vercel.com/account/tokens.

---

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

# Ruim — token visível no histórico do shell e listagens de processos
vercel deploy --token "vca_abc123"

# Bom — CLI lê VERCEL_TOKEN do ambiente
export VERCEL_TOKEN="vca_abc123"
vercel deploy

Passo 2: Localizar o Projeto e o Time

Da mesma forma, verifique o ID do projeto e o escopo do time. Eles permitem que a CLI aponte para o projeto certo sem precisar de vercel link.

# Verifique o ambiente
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

# Ou verifique .env
grep -i 'vercel' .env 2>/dev/null

Se você tem uma URL de projeto (ex.: https://vercel.com/my-team/my-project), extraia o slug do time:

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

Se você tem tanto VERCEL_ORG_ID quanto 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 o Vercel CLI esteja instalado e atualizado:

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 baseado 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 estão definidos no ambiente, implante diretamente:

vercel deploy -y --no-wait

Com escopo de time (via VERCEL_ORG_ID ou --scope):

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

Produção (apenas quando solicitado explicitamente):

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

Verifique o status:

vercel inspect <deployment-url>

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

Use isso quando você tem um token e time, mas nenhum ID de projeto pré-existente.

Verifique o estado do projeto primeiro

# O projeto tem um remote git?
git remote get-url origin 2>/dev/null

# Já está vinculado a um projeto da Vercel?
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

Vincule o projeto

Com remote git (preferido):

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

Lê o remote git e conecta ao projeto correspondente da Vercel. Cria .vercel/repo.json. Mais confiável do que vercel link simples, que combina pelo nome do diretório.

Sem remote git:

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

Cria .vercel/project.json.

Vincular a um projeto específico por nome:

vercel link --project <project-name> --scope <team-slug> -y

Se o projeto já estiver vinculado, verifique orgId em .vercel/project.json ou .vercel/repo.json para confirmar que corresponde ao time pretendido.

Implante após vincular

A) Implantação via Git Push — tem remote git (preferido)

Pushes git disparam implantações automáticas na Vercel.

1. Pergunte ao usuário antes de fazer push. Nunca faça push sem aprovação explícita.
2. Commit e push:

   git add .
   git commit -m "deploy: <descricao das alteracoes>"
   git push
   

3. A Vercel faz o build automaticamente. Branches que não são de produção recebem implantações de preview.
4. Obtenha a URL da implantação:

   sleep 5
   vercel ls --format json --scope <team-slug>
   

   Encontre a entrada mais recente no array deployments.

B) Implantação via CLI — sem remote git

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

Verifique o status:

vercel inspect <deployment-url>

Implantando de um Repositório Remoto (código não clonado localmente)

1. Clone o repositório:

   git clone <repo-url>
   cd <repo-name>
   

2. Vincule à Vercel:

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

3. Implante via git push (se você tiver acesso de push) ou via CLI.

Sobre o Diretório .vercel/

Um projeto vinculado tem:

• .vercel/project.json — de vercel link. Contém projectId e orgId.
• .vercel/repo.json — de vercel link --repo. Contém orgId, remoteName e um mapa projects.

Não é necessário quando VERCEL_ORG_ID + VERCEL_PROJECT_ID estão ambos definidos no ambiente.

NÃO execute vercel project inspect ou vercel link em um diretório não vinculado para detectar estado — eles solicitarão interativamente ou vincularão silenciosamente como efeito colateral. vercel ls é seguro (em um diretório não vinculado, ele mostra todas as implantações para o escopo por padrão). vercel whoami é seguro em qualquer lugar.

Gerenciando Variáveis de Ambiente

# Definir para todos os ambientes
echo "valor" | vercel env add NOME_DA_VAR --scope <team-slug>

# Definir para um ambiente específico (production, preview, development)
echo "valor" | vercel env add NOME_DA_VAR production --scope <team-slug>

# Listar variáveis de ambiente
vercel env ls --scope <team-slug>

# Baixar variáveis de ambiente para o arquivo .env.local
vercel env pull --scope <team-slug>

# Remover uma variável
vercel env rm NOME_DA_VAR --scope <team-slug> -y

Inspecionando Implantações

# Listar implantações recentes
vercel ls --format json --scope <team-slug>

# Inspecionar uma implantação específica
vercel inspect <deployment-url>

# Ver logs de build (requer Vercel CLI v35+)
vercel inspect <deployment-url> --logs

# Ver logs de solicitação de runtime (segue ao vivo por padrão; adicione --no-follow para um snapshot único)
vercel logs <deployment-url>

Gerenciando Domínios

# Listar domínios
vercel domains ls --scope <team-slug>

# Adicionar um domínio ao projeto — diretório vinculado ou vinculado por env (1 argumento)
vercel domains add <dominio> --scope <team-slug>

# Adicionar um domínio — diretório não vinculado (requer <projeto> posicional)
vercel domains add <dominio> <projeto> --scope <team-slug>

Mudanças de Plano em Projetos Stripe

Se este projeto é gerenciado por Stripe Projects. Pergunte ao usuário antes de executar qualquer alteração de plano paga ou destrutiva — upgrades cobram um cartão real, downgrades removem assentos.

Primeiro execute stripe projects status --json para confirmar o nome local do recurso da Vercel. Os exemplos abaixo assumem o padrão (vercel-plan); substitua pelo nome real se foi renomeado no momento de stripe projects add.

• Atualizar para Pro: stripe projects add vercel/pro (ou stripe projects upgrade vercel-plan pro)
• Rebaixar para Hobby: stripe projects downgrade vercel-plan hobby

O que o Pro oferece

• Taxa de plataforma de $20/mês, inclui $20/mês de crédito de uso.
• Máquinas de build Turbo (30 vCPUs, 60 GB de memória) por padrão para novos projetos — builds significativamente mais rápidos que Hobby.
• 1 assento de implantação + assentos ilimitados de Visualizador gratuitos (colaboradores somente leitura, comentários em preview).
• Alocações incluídas mais altas (1 TB de Transferência de Dados Rápida, 10 milhões de Solicitações de Borda por mês).
• Complementos pagos disponíveis: SAML SSO, HIPAA BAA, Flags Explorer, Observability Plus, Speed Insights, Web Analytics Plus.

Detalhes completos: https://vercel.com/docs/plans/pro-plan

Acordo de Trabalho

• Nunca passe VERCEL_TOKEN como flag --token. Exporte-o como variável de ambiente e deixe a CLI lê-lo nativamente.
• Verifique o ambiente por tokens antes de perguntar ao usuário. Primeiro olhe no ambiente atual e arquivos .env.
• Padrão para implantações de preview. Somente implante em produção quando solicitado explicitamente.
• Pergunte antes de fazer push para o git. Nunca faça push de commits sem a aprovação do usuário.
• Não modifique arquivos .vercel/ diretamente. A CLI gerencia este diretório. Lê-los (ex.: para verificar orgId) é aceitável.
• Não use curl/faça fetch de URLs implantadas para verificar. Apenas retorne o link para o usuário.
• Use --format json quando a saída estruturada ajudar em etapas posteriores.
• Use -y em comandos que solicitam confirmação para evitar bloqueio interativo.

Solução de Problemas

Token não encontrado

Verifique o ambiente e quaisquer arquivos .env presentes:

printenv | grep -i vercel
grep -i vercel .env 2>/dev/null

Erro de autenticação

Se a CLI falhar com Authentication required:

• O token pode estar expirado ou inválido.
• Verifique: vercel whoami (usa VERCEL_TOKEN do ambiente).
• Peça ao usuário um novo token.

Time errado

Verifique se o escopo está correto:

vercel whoami --scope <team-slug>

Falha no build

Verifique os logs de build:

vercel inspect <deployment-url> --logs

Causas comuns:

• Dependências ausentes — certifique-se de que package.json está completo e comitado.
• Variáveis de ambiente ausentes — adicione com vercel env add.
• Configuração incorreta do framework — verifique vercel.json. A Vercel detecta automaticamente frameworks (Next.js, Remix, Vite, etc.) a partir do package.json; substitua com vercel.json se a detecção estiver errada.

CLI não instalada

npm install -g vercel