Vercel CLI avec tokens

Déployez et gérez les projets sur Vercel avec le CLI en utilisant l'authentification par token, sans dépendre de vercel login.

Étape 1 : Localiser le token Vercel

Avant d'exécuter une commande Vercel CLI, identifiez d'où provient le token. Parcourez ces scénarios dans l'ordre :

A) VERCEL_TOKEN est déjà défini dans l'environnement

printenv VERCEL_TOKEN

Si cela retourne une valeur, vous êtes prêt. Passez à l'étape 2.

B) Le token est dans un fichier .env sous VERCEL_TOKEN

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

S'il est trouvé, exportez-le :

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

C) Le token est dans un fichier .env sous un nom différent

Cherchez toute variable qui ressemble à un token Vercel (les tokens Vercel commencent généralement par vca_) :

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

Inspectez le résultat pour identifier quelle variable contient le token, puis exportez-la en tant que VERCEL_TOKEN :

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

D) Aucun token trouvé — demandez à l'utilisateur

Si aucune des méthodes précédentes ne donne de token, demandez à l'utilisateur d'en fournir un. Il peut créer un token d'accès Vercel sur vercel.com/account/tokens.

Important : Une fois que VERCEL_TOKEN est exporté comme variable d'environnement, le Vercel CLI le lit nativement — ne le passez pas comme option --token. Mettre des secrets dans les arguments de ligne de commande les expose dans l'historique du shell et les listes de processus.

# Mauvais — token visible dans l'historique du shell et les listes de processus
vercel deploy --token "vca_abc123"

# Bon — le CLI lit VERCEL_TOKEN depuis l'environnement
export VERCEL_TOKEN="vca_abc123"
vercel deploy

Étape 2 : Localiser le projet et l'équipe

De même, vérifiez l'ID du projet et le scope de l'équipe. Ceux-ci permettent au CLI de cibler le bon projet sans avoir besoin de vercel link.

# Vérifiez l'environnement
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

# Ou vérifiez .env
grep -i 'vercel' .env 2>/dev/null

Si vous avez une URL de projet (par ex. https://vercel.com/my-team/my-project), extrayez le slug de l'équipe :

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

Si vous avez à la fois VERCEL_ORG_ID et VERCEL_PROJECT_ID dans votre environnement, exportez-les — le CLI les utilisera automatiquement et ignorera tout répertoire .vercel/ :

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

Remarque : VERCEL_ORG_ID et VERCEL_PROJECT_ID doivent être définis ensemble — définir un seul provoque une erreur.

Configuration du CLI

Assurez-vous que le Vercel CLI est installé et à jour :

npm install -g vercel
vercel --version

Déployer un projet

Déployez toujours en aperçu sauf si l'utilisateur demande explicitement la production. Choisissez une méthode en fonction de ce que vous avez disponible.

Déploiement rapide (avez l'ID du projet — aucune liaison nécessaire)

Quand VERCEL_TOKEN et VERCEL_PROJECT_ID sont définis dans l'environnement, déployez directement :

vercel deploy -y --no-wait

Avec un scope d'équipe (soit via VERCEL_ORG_ID soit via --scope) :

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

Production (seulement si explicitement demandé) :

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

Vérifiez le statut :

vercel inspect <deployment-url>

Flux de déploiement complet (pas d'ID de projet — besoin de liaison)

À utiliser quand vous avez un token et une équipe mais pas d'ID de projet préexistant.

Vérifiez d'abord l'état du projet

# Le projet a-t-il une remote git ?
git remote get-url origin 2>/dev/null

# Est-il déjà lié à un projet Vercel ?
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

Liez le projet

Avec remote git (recommandé) :

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

Lit la remote git et se connecte au projet Vercel correspondant. Crée .vercel/repo.json. Plus fiable que plain vercel link, qui associe par nom de répertoire.

Sans remote git :

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

Crée .vercel/project.json.

Liez à un projet spécifique par nom :

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

Si le projet est déjà lié, vérifiez orgId dans .vercel/project.json ou .vercel/repo.json pour confirmer qu'il correspond à l'équipe prévue.

Déployez après la liaison

A) Déploiement par git push — a une remote git (recommandé)

Les git push déclenchent des déploiements Vercel automatiques.

1. Demandez à l'utilisateur avant de push. Ne poussez jamais sans approbation explicite.
2. Committez et poussez :

   git add .
   git commit -m "deploy: <description of changes>"
   git push

3. Vercel construit automatiquement. Les branches non-production obtiennent des déploiements d'aperçu.
4. Récupérez l'URL de déploiement :

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

   Trouvez l'entrée la plus récente dans le tableau deployments.

B) Déploiement par CLI — sans remote git

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

Vérifiez le statut :

vercel inspect <deployment-url>

Déployer depuis un dépôt distant (code non cloné localement)

1. Clonez le dépôt :

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

2. Liez à Vercel :

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

3. Déployez via git push (si vous avez accès en push) ou déploiement par CLI.

À propos du répertoire .vercel/

Un projet lié contient soit :

• .vercel/project.json — de vercel link. Contient projectId et orgId.
• .vercel/repo.json — de vercel link --repo. Contient orgId, remoteName et une map projects.

Non nécessaire quand VERCEL_ORG_ID + VERCEL_PROJECT_ID sont tous deux définis dans l'environnement.

Ne lancez PAS vercel project inspect ou vercel link dans un répertoire non lié pour détecter l'état — ils vont interactivement demander ou lier silencieusement en tant qu'effet secondaire. vercel ls est sûr (dans un répertoire non lié, il affiche par défaut tous les déploiements pour le scope). vercel whoami est sûr n'importe où.

Gérer les variables d'environnement

# Définir pour tous les environnements
echo "value" | vercel env add VAR_NAME --scope <team-slug>

# Définir pour un environnement spécifique (production, preview, development)
echo "value" | vercel env add VAR_NAME production --scope <team-slug>

# Lister les variables d'environnement
vercel env ls --scope <team-slug>

# Tirer les variables d'env vers un fichier local .env.local
vercel env pull --scope <team-slug>

# Supprimer une variable
vercel env rm VAR_NAME --scope <team-slug> -y

Inspecter les déploiements

# Lister les déploiements récents
vercel ls --format json --scope <team-slug>

# Inspecter un déploiement spécifique
vercel inspect <deployment-url>

# Voir les logs de build (nécessite Vercel CLI v35+)
vercel inspect <deployment-url> --logs

# Voir les logs de requête runtime (suit en direct par défaut ; ajoutez --no-follow pour un snapshot unique)
vercel logs <deployment-url>

Gérer les domaines

# Lister les domaines
vercel domains ls --scope <team-slug>

# Ajouter un domaine au projet — répertoire lié ou lié par env (1 arg)
vercel domains add <domain> --scope <team-slug>

# Ajouter un domaine — répertoire non lié (nécessite <project> positionnel)
vercel domains add <domain> <project> --scope <team-slug>

Changements de plan Vercel via Stripe Projects

Si ce projet est géré par Stripe Projects. Demandez à l'utilisateur avant de lancer tout changement de plan payant ou destructif — les mises à niveau facturent une vraie carte, les rétrogradations suppriment des sièges.

D'abord lancez stripe projects status --json pour confirmer le nom local de la ressource Vercel. Les exemples ci-dessous supposent le défaut (vercel-plan) ; remplacez le nom réel s'il a été renommé lors de stripe projects add.

• Mettre à niveau vers Pro : stripe projects add vercel/pro (ou stripe projects upgrade vercel-plan pro)
• Rétrograder vers Hobby : stripe projects downgrade vercel-plan hobby

Ce que Pro vous donne

• Frais de plateforme $20/mois, incluent $20/mois de crédit d'utilisation.
• Machines Turbo build (30 vCPUs, 60 GB mémoire) par défaut pour les nouveaux projets — constructions significativement plus rapides qu'Hobby.
• 1 siège déployant + sièges Viewer illimités gratuits (collaborateurs en lecture seule, commentaires d'aperçu).
• Allocations incluses plus élevées (1 TB Fast Data Transfer, 10M Edge Requests par mois).
• Modules complémentaires payants disponibles : SAML SSO, HIPAA BAA, Flags Explorer, Observability Plus, Speed Insights, Web Analytics Plus.

Détails complets : https://vercel.com/docs/plans/pro-plan

Accord de travail

• Ne passez jamais VERCEL_TOKEN comme option --token. Exportez-le comme variable d'environnement et laissez le CLI le lire nativement.
• Vérifiez l'environnement pour les tokens avant de demander à l'utilisateur. Cherchez d'abord dans l'env courant et les fichiers .env.
• Préférez les déploiements d'aperçu. Déployez seulement en production quand explicitement demandé.
• Demandez avant de push vers git. Ne poussez jamais de commits sans approbation de l'utilisateur.
• Ne modifiez pas les fichiers .vercel/ directement. Le CLI gère ce répertoire. Lire ceux-ci (par ex. pour vérifier orgId) est acceptable.
• Ne curl/fetch pas les URLs déployées pour vérifier. Retournez simplement le lien à l'utilisateur.
• Utilisez --format json quand une sortie structurée aidera pour les étapes suivantes.
• Utilisez -y sur les commandes qui demandent une confirmation pour éviter le blocage interactif.

Dépannage

Token non trouvé

Vérifiez l'environnement et tout fichier .env présent :

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

Erreur d'authentification

Si le CLI échoue avec Authentication required :

• Le token peut être expiré ou invalide.
• Vérifiez : vercel whoami (utilise VERCEL_TOKEN depuis l'environnement).
• Demandez à l'utilisateur un token frais.

Mauvaise équipe

Vérifiez que le scope est correct :

vercel whoami --scope <team-slug>

Échec de la construction

Vérifiez les logs de build :

vercel inspect <deployment-url> --logs

Causes courantes :

• Dépendances manquantes — assurez-vous que package.json est complet et commité.
• Variables d'environnement manquantes — ajoutez avec vercel env add.
• Framework mal configuré — vérifiez vercel.json. Vercel détecte automatiquement les frameworks (Next.js, Remix, Vite, etc.) depuis package.json ; remplacez par vercel.json si la détection est fausse.

CLI non installé

npm install -g vercel