vercel-cli-con-tokens

CLI de Vercel con Tokens

Despliega y gestiona proyectos en Vercel usando la CLI con autenticación basada en tokens, sin depender de vercel login.

Paso 1: Localizar el Token de Vercel

Antes de ejecutar cualquier comando de la CLI de Vercel, identifica de dónde proviene el token. Revisa estos escenarios en orden:

A) VERCEL_TOKEN ya está definido en el entorno

printenv VERCEL_TOKEN

Si esto devuelve un valor, estás listo. Ve al Paso 2.

B) El token está en un archivo .env bajo VERCEL_TOKEN

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

Si se encuentra, expórtalo:

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

C) El token está en un archivo .env con otro nombre

Busca cualquier variable que parezca un token de Vercel (los tokens de Vercel suelen comenzar con vca_):

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

Inspecciona la salida para identificar qué variable contiene el token, luego expórtala como VERCEL_TOKEN:

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

D) No se encontró token — preguntar al usuario

Si ninguno de los pasos anteriores produce un token, pídele al usuario que proporcione uno. Puede crear un token de acceso de Vercel en vercel.com/account/tokens.

---

Importante: Una vez que VERCEL_TOKEN está exportado como variable de entorno, la CLI de Vercel lo lee de forma nativa — no lo pases como bandera --token. Poner secretos en argumentos de línea de comandos los expone en el historial del shell y en listados de procesos.

# Mal — el token es visible en historial y listados de procesos
vercel deploy --token "vca_abc123"

# Bien — la CLI lee VERCEL_TOKEN del entorno
export VERCEL_TOKEN="vca_abc123"
vercel deploy

Paso 2: Localizar el Proyecto y el Equipo

De manera similar, verifica el ID del proyecto y el ámbito del equipo. Estos permiten que la CLI apunte al proyecto correcto sin necesidad de vercel link.

# Verificar el entorno
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

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

Si tienes una URL de proyecto (ej. https://vercel.com/mi-equipo/mi-proyecto), extrae el slug del equipo:

# ej. "mi-equipo" de "https://vercel.com/mi-equipo/mi-proyecto"
echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1

Si tienes tanto VERCEL_ORG_ID como VERCEL_PROJECT_ID en tu entorno, expórtalos — la CLI los usará automáticamente y omitirá cualquier directorio .vercel/:

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

Nota: VERCEL_ORG_ID y VERCEL_PROJECT_ID deben establecerse juntos — establecer solo uno causa un error.

Configuración de la CLI

Asegúrate de que la CLI de Vercel esté instalada y actualizada:

npm install -g vercel
vercel --version

Despliegue de un Proyecto

Siempre despliega como vista previa a menos que el usuario solicite explícitamente producción. Elige un método según lo que tengas disponible.

Despliegue Rápido (tienes ID del proyecto — sin necesidad de enlace)

Cuando VERCEL_TOKEN y VERCEL_PROJECT_ID están definidos en el entorno, despliega directamente:

vercel deploy -y --no-wait

Con ámbito de equipo (ya sea mediante VERCEL_ORG_ID o --scope):

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

Producción (solo cuando se solicite explícitamente):

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

Verificar estado:

vercel inspect <url-despliegue>

Flujo de Despliegue Completo (sin ID de proyecto — necesita enlace)

Usa esto cuando tengas un token y equipo pero no un ID de proyecto preexistente.

Verificar primero el estado del proyecto

# ¿El proyecto tiene un remoto git?
git remote get-url origin 2>/dev/null

# ¿Ya está vinculado a un proyecto de Vercel?
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

Vincular el proyecto

Con remoto git (preferido):

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

Lee el remoto git y se conecta al proyecto de Vercel correspondiente. Crea .vercel/repo.json. Más fiable que vercel link simple, que vincula por nombre de directorio.

Sin remoto git:

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

Crea .vercel/project.json.

Vincular a un proyecto específico por nombre:

vercel link --project <nombre-proyecto> --scope <slug-equipo> -y

Si el proyecto ya está vinculado, verifica orgId en .vercel/project.json o .vercel/repo.json para asegurarte de que coincide con el equipo previsto.

Desplegar después de vincular

A) Despliegue por Git Push — tiene remoto git (preferido)

Los pushes de Git activan despliegues automáticos en Vercel.

1. Pregunta al usuario antes de hacer push. Nunca hagas push sin aprobación explícita.
2. Haz commit y push:

   git add .
   git commit -m "deploy: <descripción de cambios>"
   git push
   

3. Vercel construye automáticamente. Las ramas que no son de producción obtienen despliegues de vista previa.
4. Recupera la URL del despliegue:

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

   Encuentra la entrada más reciente en el array deployments.

B) Despliegue por CLI — sin remoto git

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

Verificar estado:

vercel inspect <url-despliegue>

Despliegue desde un Repositorio Remoto (código no clonado localmente)

1. Clona el repositorio:

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

2. Vincula a Vercel:

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

3. Despliega mediante git push (si tienes acceso de push) o despliegue por CLI.

Acerca del Directorio .vercel/

Un proyecto vinculado tiene:

• .vercel/project.json — de vercel link. Contiene projectId y orgId.
• .vercel/repo.json — de vercel link --repo. Contiene orgId, remoteName y un mapa de projects.

No necesario cuando VERCEL_ORG_ID + VERCEL_PROJECT_ID están ambos definidos en el entorno.

NO ejecutes vercel project inspect ni vercel link en un directorio no vinculado para detectar estado — preguntarán interactivamente o vincularán silenciosamente como efecto secundario. vercel ls es seguro (en un directorio no vinculado, por defecto muestra todos los despliegues del ámbito). vercel whoami es seguro en cualquier lugar.

Gestión de Variables de Entorno

# Establecer para todos los entornos
echo "valor" | vercel env add NOMBRE_VAR --scope <slug-equipo>

# Establecer para un entorno específico (production, preview, development)
echo "valor" | vercel env add NOMBRE_VAR production --scope <slug-equipo>

# Listar variables de entorno
vercel env ls --scope <slug-equipo>

# Traer vars de entorno a archivo .env.local
vercel env pull --scope <slug-equipo>

# Eliminar una variable
vercel env rm NOMBRE_VAR --scope <slug-equipo> -y

Inspección de Despliegues

# Listar despliegues recientes
vercel ls --format json --scope <slug-equipo>

# Inspeccionar un despliegue específico
vercel inspect <url-despliegue>

# Ver logs de construcción (requiere CLI v35+)
vercel inspect <url-despliegue> --logs

# Ver logs de solicitudes en tiempo real (sigue en vivo por defecto; añade --no-follow para una instantánea única)
vercel logs <url-despliegue>

Gestión de Dominios

# Listar dominios
vercel domains ls --scope <slug-equipo>

# Añadir un dominio al proyecto — directorio vinculado o con env (1 argumento)
vercel domains add <dominio> --scope <slug-equipo>

# Añadir un dominio — directorio no vinculado (requiere <proyecto> posicional)
vercel domains add <dominio> <proyecto> --scope <slug-equipo>

Cambios de Plan en Proyectos Stripe

Si este proyecto es gestionado por Stripe Projects. Pregunta al usuario antes de ejecutar cualquier cambio de plan pago o destructivo — las actualizaciones cobran una tarjeta real, las degradaciones eliminan asientos.

Primero ejecuta stripe projects status --json para confirmar el nombre local del recurso de Vercel. Los ejemplos asumen el predeterminado (vercel-plan); sustituye el nombre real si se renombró al hacer stripe projects add.

• Actualizar a Pro: stripe projects add vercel/pro (o stripe projects upgrade vercel-plan pro)
• Degradar a Hobby: stripe projects downgrade vercel-plan hobby

Qué ofrece Pro

• Cuota de plataforma de $20/mes, incluye $20/mes de crédito de uso.
• Máquinas de construcción Turbo (30 vCPUs, 60 GB de memoria) por defecto para nuevos proyectos — construcciones significativamente más rápidas que Hobby.
• 1 asiento de despliegue + asientos ilimitados de Visor gratuitos (colaboradores de solo lectura, comentarios de vista previa).
• Asignaciones incluidas más altas (1 TB de Transferencia Rápida de Datos, 10M Solicitudes Edge por mes).
• Complementos de pago disponibles: SAML SSO, HIPAA BAA, Flags Explorer, Observability Plus, Speed Insights, Web Analytics Plus.

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

Acuerdo de Trabajo

• Nunca pases VERCEL_TOKEN como bandera --token. Expórtalo como variable de entorno y deja que la CLI lo lea de forma nativa.
• Verifica el entorno en busca de tokens antes de preguntar al usuario. Revisa primero el entorno actual y los archivos .env.
• Por defecto, despliegues de vista previa. Solo despliega a producción cuando se solicite explícitamente.
• Pregunta antes de hacer push a git. Nunca hagas push de commits sin la aprobación del usuario.
• No modifiques archivos .vercel/ directamente. La CLI gestiona este directorio. Leerlos (ej. para verificar orgId) está bien.
• No hagas curl/fetch a las URLs desplegadas para verificar. Simplemente devuelve el enlace al usuario.
• Usa --format json cuando la salida estructurada ayude con pasos posteriores.
• Usa -y en comandos que pidan confirmación para evitar bloqueo interactivo.

Solución de Problemas

Token no encontrado

Verifica el entorno y cualquier archivo .env presente:

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

Error de autenticación

Si la CLI falla con Authentication required:

• El token puede haber expirado o ser inválido.
• Verifica: vercel whoami (usa VERCEL_TOKEN del entorno).
• Pide al usuario un token nuevo.

Equipo incorrecto

Verifica que el ámbito sea correcto:

vercel whoami --scope <slug-equipo>

Fallo en la construcción

Revisa los logs de construcción:

vercel inspect <url-despliegue> --logs

Causas comunes:

• Dependencias faltantes — asegúrate de que package.json esté completo y commiteado.
• Variables de entorno faltantes — agrégalas con vercel env add.
• Mala configuración del framework — verifica vercel.json. Vercel detecta automáticamente frameworks (Next.js, Remix, Vite, etc.) desde package.json; sobrescribe con vercel.json si la detección es incorrecta.

CLI no instalada

npm install -g vercel