vercel-cli-avec-tokens

CLI Vercel avec jetons

Déployez et gérez des projets sur Vercel en utilisant la CLI avec une authentification par jeton, sans dépendre de vercel login.

Étape 1 : Localiser le jeton Vercel

Avant d'exécuter des commandes CLI Vercel, identifiez d'où provient le jeton. 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 jeton se trouve 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 jeton se trouve dans un fichier .env sous un nom différent

Recherchez toute variable qui ressemble à un jeton Vercel (les jetons Vercel commencent généralement par vca_) :

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

Inspectez la sortie pour identifier quelle variable contient le jeton, puis exportez-la sous le nom VERCEL_TOKEN :

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

D) Aucun jeton trouvé — demander à l'utilisateur

Si aucune des méthodes ci-dessus ne produit de jeton, demandez à l'utilisateur d'en fournir un. Il peut créer un jeton d'accès Vercel sur vercel.com/account/tokens.

---

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

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

# Bon — la 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 la portée de l'équipe. Cela permet à la CLI de cibler le bon projet sans avoir besoin de vercel link.

# Vérifier l'environnement
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

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

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

# par ex. "mon-equipe" depuis "https://vercel.com/mon-equipe/mon-projet"
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 — la 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 CLI

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

npm install -g vercel
vercel --version

Déployer un projet

Déployez toujours en mode prévisualisation sauf si l'utilisateur demande explicitement la production. Choisissez une méthode en fonction de ce dont vous disposez.

Déploiement rapide (avec ID de projet — pas besoin de liaison)

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

vercel deploy -y --no-wait

Avec une portée d'équipe (via VERCEL_ORG_ID ou --scope) :

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

Production (uniquement sur demande explicite) :

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

Vérifier le statut :

vercel inspect <url-deploiement>

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

Utilisez ceci lorsque vous avez un jeton et une équipe mais pas d'ID de projet préexistant.

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

# Le projet a-t-il un dépôt distant 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

Lier le projet

Avec dépôt distant git (recommandé) :

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

Lit le dépôt distant git et se connecte au projet Vercel correspondant. Crée .vercel/repo.json. Plus fiable que vercel link simple, qui correspond par nom de répertoire.

Sans dépôt distant git :

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

Crée .vercel/project.json.

Lier à un projet spécifique par nom :

vercel link --project <nom-projet> --scope <slug-equipe> -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éployer après liaison

A) Déploiement par push Git — avec dépôt distant (recommandé)

Les pushes Git déclenchent des déploiements automatiques sur Vercel.

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

   git add .
   git commit -m "deploy: <description des changements>"
   git push
   

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

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

   Trouvez la dernière entrée dans le tableau deployments.

B) Déploiement CLI — sans dépôt distant

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

Vérifier le statut :

vercel inspect <url-deploiement>

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

1. Clonez le dépôt :

   git clone <url-depot>
   cd <nom-depot>
   

2. Liez à Vercel :

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

3. Déployez via push git (si vous avez les droits d'écriture) ou déploiement CLI.

À propos du répertoire .vercel/

Un projet lié possède soit :

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

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

N'exécutez PAS vercel project inspect ou vercel link dans un répertoire non lié pour détecter l'état — ils inviteront de manière interactive ou lieront silencieusement par effet de bord. vercel ls est sûr (dans un répertoire non lié, il affiche par défaut tous les déploiements pour la portée). vercel whoami est sûr partout.

Gérer les variables d'environnement

# Définir pour tous les environnements
echo "valeur" | vercel env add NOM_VAR --scope <slug-equipe>

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

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

# Récupérer les variables d'environnement dans un fichier .env.local
vercel env pull --scope <slug-equipe>

# Supprimer une variable
vercel env rm NOM_VAR --scope <slug-equipe> -y

Inspecter les déploiements

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

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

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

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

Gérer les domaines

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

# Ajouter un domaine au projet — répertoire lié ou lié par variable d'environnement (1 argument)
vercel domains add <domaine> --scope <slug-equipe>

# Ajouter un domaine — répertoire non lié (nécessite l'argument positionnel <projet>)
vercel domains add <domaine> <projet> --scope <slug-equipe>

Modifications de plan Stripe Projects

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

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

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

Ce que Pro vous offre

• Frais de plateforme de 20$/mois, inclut 20$/mois de crédit d'utilisation.
• Machines de build Turbo (30 vCPU, 60 Go de mémoire) par défaut pour les nouveaux projets — builds nettement plus rapides que Hobby.
• 1 siège de déploiement + un nombre illimité de sièges Viewer gratuits (collaborateurs en lecture seule, commentaires de prévisualisation).
• Allocations incluses plus élevées (1 To de transfert de données rapide, 10 M de requêtes Edge 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 indicateur --token. Exportez-le comme variable d'environnement et laissez la CLI le lire nativement.
• Vérifiez l'environnement pour les jetons avant de demander à l'utilisateur. Cherchez d'abord dans l'environnement actuel et les fichiers .env.
• Par défaut, déployez en prévisualisation. Ne déployez en production que sur demande explicite.
• Demandez avant de pousser vers git. Ne poussez jamais de commits sans l'approbation de l'utilisateur.
• Ne modifiez pas les fichiers .vercel/ directement. La CLI gère ce répertoire. Les lire (par ex. pour vérifier orgId) est acceptable.
• N'utilisez pas curl/fetch sur les URLs déployées pour vérifier. Contentez-vous de retourner le lien à l'utilisateur.
• Utilisez --format json lorsque la sortie structurée facilitera les étapes suivantes.
• Utilisez -y sur les commandes qui demandent une confirmation pour éviter le blocage interactif.

Dépannage

Jeton 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 la CLI échoue avec Authentication required :

• Le jeton a peut-être expiré ou est invalide.
• Vérifiez : vercel whoami (utilise VERCEL_TOKEN de l'environnement).
• Demandez un nouveau jeton à l'utilisateur.

Mauvaise équipe

Vérifiez que la portée est correcte :

vercel whoami --scope <slug-equipe>

Échec de build

Vérifiez les logs de build :

vercel inspect <url-deploiement> --logs

Causes courantes :

• Dépendances manquantes — assurez-vous que package.json est complet et committé.
• Variables d'environnement manquantes — ajoutez avec vercel env add.
• Mauvaise configuration du framework — vérifiez vercel.json. Vercel détecte automatiquement les frameworks (Next.js, Remix, Vite, etc.) depuis package.json ; remplacez avec vercel.json si la détection est incorrecte.

CLI non installée

npm install -g vercel