Vercel CLI mit Tokens

Was macht Vercel CLI mit Tokens?

Projekte auf Vercel mit der CLI und tokenbasierter Authentifizierung deployen und verwalten – ohne vercel login.

Schritt 1: Vercel-Token finden

Bevor Vercel CLI-Befehle ausgeführt werden, muss herausgefunden werden, woher der Token stammt. Diese Szenarien in dieser Reihenfolge durchgehen:

A) VERCEL_TOKEN ist bereits in der Umgebung gesetzt

printenv VERCEL_TOKEN

Wenn ein Wert zurückgegeben wird, ist alles bereit. Weiter mit Schritt 2.

B) Token ist in einer .env-Datei unter VERCEL_TOKEN

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

Falls gefunden, exportieren:

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

C) Token ist in einer .env-Datei unter einem anderen Namen

Nach einer Variable suchen, die wie ein Vercel-Token aussieht (Vercel-Tokens beginnen typischerweise mit vca_):

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

Die Ausgabe prüfen, um die Variable zu identifizieren, die den Token enthält, und dann als VERCEL_TOKEN exportieren:

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

D) Kein Token gefunden – Benutzer fragen

Wenn keiner der obigen Schritte einen Token liefert, den Benutzer bitten, einen bereitzustellen. Ein Vercel-Zugangstoken kann unter vercel.com/account/tokens erstellt werden.

---

Wichtig: Sobald VERCEL_TOKEN als Umgebungsvariable exportiert ist, liest die Vercel CLI sie nativ – nicht als --token-Flag übergeben. Das Setzen von Secrets in Kommandozeilenargumenten macht sie im Shell-Verlauf und in Prozesslisten sichtbar.

# Schlecht – Token im Shell-Verlauf und in Prozesslisten sichtbar
vercel deploy --token "vca_abc123"

# Gut – CLI liest VERCEL_TOKEN aus der Umgebung
export VERCEL_TOKEN="vca_abc123"
vercel deploy

Schritt 2: Projekt und Team finden

Ähnlich nach Projekt-ID und Team-Scope suchen. Diese lassen die CLI das richtige Projekt ansteuern, ohne vercel link zu benötigen.

# Umgebungsvariablen prüfen
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

# Oder .env prüfen
grep -i 'vercel' .env 2>/dev/null

Wenn eine Projekt-URL vorhanden ist (z. B. https://vercel.com/my-team/my-project), den Team-Slug extrahieren:

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

Wenn sowohl VERCEL_ORG_ID als auch VERCEL_PROJECT_ID in der Umgebung gesetzt sind, diese exportieren – die CLI verwendet sie automatisch und überspringt das .vercel/-Verzeichnis:

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

Hinweis: VERCEL_ORG_ID und VERCEL_PROJECT_ID müssen zusammen gesetzt werden – nur eine zu setzen, verursacht einen Fehler.

CLI-Setup

Sicherstellen, dass die Vercel CLI installiert und aktuell ist:

npm install -g vercel
vercel --version

Ein Projekt deployen

Immer als Preview deployen, es sei denn, der Benutzer wünscht explizit eine Produktion. Die Methode basierend auf den verfügbaren Informationen wählen.

Schnelles Deployen (Projekt-ID vorhanden – kein Link nötig)

Wenn VERCEL_TOKEN und VERCEL_PROJECT_ID in der Umgebung gesetzt sind, direkt deployen:

vercel deploy -y --no-wait

Mit einem Team-Scope (entweder über VERCEL_ORG_ID oder --scope):

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

Produktion (nur bei expliziter Anforderung):

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

Status prüfen:

vercel inspect <deployment-url>

Vollständiger Deploy-Workflow (keine Projekt-ID – Link erforderlich)

Verwenden, wenn ein Token und ein Team, aber keine vorhandene Projekt-ID vorhanden sind.

Projektzustand zuerst prüfen

# Hat das Projekt ein Git-Remote?
git remote get-url origin 2>/dev/null

# Ist es bereits mit einem Vercel-Projekt verlinkt?
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

Projekt verlinken

Mit Git-Remote (bevorzugt):

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

Liest das Git-Remote und verbindet mit dem passenden Vercel-Projekt. Erstellt .vercel/repo.json. Zuverlässiger als vercel link ohne Optionen, das nach Verzeichnisnamen matcht.

Ohne Git-Remote:

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

Erstellt .vercel/project.json.

Mit einem bestimmten Projektnamen verlinken:

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

Wenn das Projekt bereits verlinkt ist, die orgId in .vercel/project.json oder .vercel/repo.json prüfen, um sicherzustellen, dass es mit dem beabsichtigten Team übereinstimmt.

Nach dem Verlinken deployen

A) Git-Push-Deploy – Git-Remote vorhanden (bevorzugt)

Git-Pushes lösen automatische Vercel-Deployments aus.

1. Den Benutzer vor dem Pushen fragen. Niemals ohne ausdrückliche Zustimmung pushen.
2. Committen und pushen:

   git add .
   git commit -m "deploy: <Beschreibung der Änderungen>"
   git push
   

3. Vercel erstellt automatisch. Nicht-Produktionsbranches erhalten Preview-Deployments.
4. Die Deployment-URL abrufen:

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

   Den neuesten Eintrag im deployments-Array finden.

B) CLI-Deploy – kein Git-Remote

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

Status prüfen:

vercel inspect <deployment-url>

Von einem Remote-Repository deployen (Code nicht lokal geklont)

1. Das Repository klonen:

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

2. Mit Vercel verlinken:

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

3. Über Git-Push deployen (falls Push-Zugriff vorhanden) oder CLI-Deploy.

Über das .vercel/-Verzeichnis

Ein verlinktes Projekt hat entweder:

• .vercel/project.json – von vercel link. Enthält projectId und orgId.
• .vercel/repo.json – von vercel link --repo. Enthält orgId, remoteName und eine projects-Map.

Nicht erforderlich, wenn sowohl VERCEL_ORG_ID als auch VERCEL_PROJECT_ID in der Umgebung gesetzt sind.

NIEMALS vercel project inspect oder vercel link in einem nicht verlinkten Verzeichnis ausführen, um den Zustand zu prüfen – sie würden interaktiv nachfragen oder still verlinken (Nebeneffekt). vercel ls ist sicher (in einem nicht verlinkten Verzeichnis zeigt es standardmäßig alle Deployments des Scopes). vercel whoami ist überall sicher.

Umgebungsvariablen verwalten

# Für alle Umgebungen setzen
echo "Wert" | vercel env add VAR_NAME --scope <team-slug>

# Für eine bestimmte Umgebung setzen (production, preview, development)
echo "Wert" | vercel env add VAR_NAME production --scope <team-slug>

# Umgebungsvariablen auflisten
vercel env ls --scope <team-slug>

# Umgebungsvariablen in lokale .env.local-Datei ziehen
vercel env pull --scope <team-slug>

# Eine Variable entfernen
vercel env rm VAR_NAME --scope <team-slug> -y

Deployments inspizieren

# Neueste Deployments auflisten
vercel ls --format json --scope <team-slug>

# Ein bestimmtes Deployment inspizieren
vercel inspect <deployment-url>

# Build-Logs anzeigen (erfordert Vercel CLI v35+)
vercel inspect <deployment-url> --logs

# Request-Logs zur Laufzeit anzeigen (standardmäßig live folgen; --no-follow für einen einmaligen Snapshot)
vercel logs <deployment-url>

Domains verwalten

# Domains auflisten
vercel domains ls --scope <team-slug>

# Eine Domain zum Projekt hinzufügen – verlinktes oder env-verlinktes Verzeichnis (1 Argument)
vercel domains add <domain> --scope <team-slug>

# Eine Domain hinzufügen – nicht verlinktes Verzeichnis (erfordert <project> als Position)
vercel domains add <domain> <project> --scope <team-slug>

Stripe-Projekte: Planänderungen

Wenn dieses Projekt von Stripe Projects verwaltet wird. Den Benutzer vor kostenpflichtigen oder destruktiven Planänderungen fragen – Upgrades belasten eine echte Kreditkarte, Downgrades entfernen Plätze.

Zuerst stripe projects status --json ausführen, um den lokalen Namen der Vercel-Ressource zu bestätigen. Die Beispiele unten nehmen den Standard (vercel-plan) an; den tatsächlichen Namen verwenden, falls er beim stripe projects add umbenannt wurde.

• Upgrade auf Pro: stripe projects add vercel/pro (oder stripe projects upgrade vercel-plan pro)
• Downgrade auf Hobby: stripe projects downgrade vercel-plan hobby

Was Pro bietet

• 20 $/Monat Plattformgebühr, inklusive 20 $/Monat Nutzungsguthaben.
• Turbo-Build-Maschinen (30 vCPUs, 60 GB RAM) standardmäßig für neue Projekte – deutlich schnellere Builds als Hobby.
• 1 deployender Sitz + unbegrenzte kostenlose Viewer-Sitze (schreibgeschützte Mitarbeiter, Preview-Kommentare).
• Höhere inkludierte Kontingente (1 TB Fast Data Transfer, 10 Mio. Edge Requests pro Monat).
• Kostenpflichtige Add-ons verfügbar: SAML SSO, HIPAA BAA, Flags Explorer, Observability Plus, Speed Insights, Web Analytics Plus.

Vollständige Details: https://vercel.com/docs/plans/pro-plan

Arbeitsabsprachen

• VERCEL_TOKEN niemals als --token-Flag übergeben. Als Umgebungsvariable exportieren und von der CLI nativ lesen lassen.
• Vor dem Benutzer nach Tokens suchen. Zuerst in der aktuellen Umgebung und in .env-Dateien suchen.
• Standardmäßig Preview-Deployments verwenden. Nur auf Produktion deployen, wenn explizit darum gebeten wird.
• Vor dem Pushen zu Git fragen. Niemals Commits ohne Zustimmung des Benutzers pushen.
• .vercel/-Dateien nicht direkt ändern. Die CLI verwaltet dieses Verzeichnis. Lesen (z. B. zum Überprüfen der orgId) ist in Ordnung.
• Deployment-URLs nicht über curl/fetch prüfen. Den Link einfach an den Benutzer zurückgeben.
• --format json verwenden, wenn strukturierte Ausgabe bei nachfolgenden Schritten hilft.
• -y verwenden bei Befehlen, die eine Bestätigung erfordern, um interaktive Blocks zu vermeiden.

Fehlerbehebung

Token nicht gefunden

Die Umgebung und vorhandene .env-Dateien prüfen:

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

Authentifizierungsfehler

Wenn die CLI mit Authentication required fehlschlägt:

• Der Token ist möglicherweise abgelaufen oder ungültig.
• Überprüfen: vercel whoami (verwendet VERCEL_TOKEN aus der Umgebung).
• Den Benutzer um einen neuen Token bitten.

Falsches Team

Überprüfen, ob der Scope korrekt ist:

vercel whoami --scope <team-slug>

Build-Fehler

Die Build-Logs prüfen:

vercel inspect <deployment-url> --logs

Häufige Ursachen:

• Fehlende Abhängigkeiten – package.json vollständig und committed.
• Fehlende Umgebungsvariablen – mit vercel env add hinzufügen.
• Falsche Framework-Konfiguration – vercel.json prüfen. Vercel erkennt Frameworks (Next.js, Remix, Vite usw.) automatisch aus package.json; bei falscher Erkennung mit vercel.json überschreiben.

CLI nicht installiert

npm install -g vercel