Wie installiere und nutze ich die Perspective CLI?

Die Perspective CLI ist ein Kommandozeilen-Tool, das dein Terminal mit deinem Perspective-Konto verbindet. Sie läuft über dieselbe API wie die API App, du kannst also Funnels auflisten, Kontakte lesen und aktualisieren und Funnel-Metriken abrufen, ohne dich durchs Dashboard zu klicken. Alles kommt als JSON zurück und lässt sich damit gut in Skripten, geplanten Jobs oder einem AI-Coding-Assistenten weiterverwenden.

TL;DR

Installiere die CLI mit npm install -g @perspective-software/cli. Du brauchst Node.js 24, und sie läuft unter Windows, macOS und Linux.
Melde dich einmalig mit perspective auth login an, das öffnet deinen Browser. Skripte und CI-Jobs nutzen stattdessen einen API Schlüssel.
Hol dir deine Daten mit Befehlen wie perspective funnels list, perspective contacts list <funnelId> und perspective metrics kpi <funnelId> conversion_rate --days 30.

ℹ️ Wichtig: Die CLI braucht API-Zugriff, und der ist nur im Scale Plan und im alten Volume Plan enthalten. Außerdem muss dein Abo aktiv sein. In anderen Plänen kannst du die CLI zwar installieren und dich anmelden, die Befehle contacts und metrics geben dann aber einen Fehler zurück. Was dir API-Zugriff sonst noch bringt, steht in Was kann ich mit der API App in Perspective machen?

Was kann ich mit der Perspective CLI machen?

Die CLI deckt drei Bereiche ab: deine Funnels, deine Kontakte und deine Funnel-Metriken. Jeder Befehl gibt JSON aus. Du kannst es also an ein Tool wie jq weiterleiten, in eine Datei speichern oder in dein eigenes Reporting-Skript einspeisen.

Pagination und Zeiträume übernimmt die CLI für dich, diese Requests musst du also nicht selbst bauen.

Funnels bauen oder bearbeiten kann die CLI nicht. Wenn AI einen Funnel für dich erstellen soll, nutze stattdessen den Perspective MCP.

Alle technischen Details dazu findest du in unserer Entwickler-Dokumentation.

Perspective CLI Dokumentation →

Wie installiere ich die Perspective CLI?

Die CLI läuft unter Windows, macOS und Linux. Bei älteren Node.js-Versionen können bei der Installation Warnungen oder Fehler auftreten. Installiere sie global mit npm, dafür brauchst du Node.js 24:

npm install -g @perspective-software/cli

Wenn du pnpm nutzt, führe stattdessen pnpm add -g @perspective-software/cli aus.

Prüfe mit perspective --version, ob alles geklappt hat.

Wenn du nur einen einzelnen Befehl ausprobieren willst, ohne etwas zu installieren, nutze npx @perspective-software/cli <command>.

Wie verbinde ich die CLI mit meinem Perspective-Konto?

Es gibt zwei Wege, dich anzumelden, und die CLI nutzt standardmäßig den Browser.

Methode	Befehl	Am besten für
Browser-Anmeldung	`perspective auth login`	Arbeiten auf deinem eigenen Rechner
API-Schlüssel	`perspective auth login --method api-key`	Skripte, Server, CI-Jobs oder einen Schlüssel, den sich dein Team teilt

Mit perspective auth status siehst du, welche Methode aktiv ist, woher sie kommt und wann eine Browser-Anmeldung abläuft. perspective auth logout löscht deine gespeicherten Zugangsdaten.

Deine Zugangsdaten liegen in ~/.config/perspective/credentials.json, in einer Datei, die nur du lesen kannst.

Wie melde ich mich in Perspective CLI über den Browser an?

Führe perspective auth login aus. Die CLI öffnet deinen Browser auf der Perspective-Anmeldeseite, dieselbe Anmeldung, die auch der Perspective MCP nutzt, und speichert die Session, sobald du fertig bist.

Deine Session erneuert sich selbst, du meldest dich also nur einmal an.

Wenn sich kein Browser öffnet, zum Beispiel über SSH oder in einem Container, nutze perspective auth login --no-open. Die CLI gibt dir dann einen Anmelde-Link, den du in jedem Browser auf demselben Rechner öffnen kannst, und die Anmeldung wird im Terminal abgeschlossen.

Wie melde ich mich in Perspective CLI mit einem API-Schlüssel an?

Erstelle den Schlüssel in deinen Account-Einstellungen, scrolle runter zu API-Schlüssel und klicke auf Erstellen. Vergib einen Namen, wähle die passenden Datenberechtigungen und den gewünschten Workspace-Zugriff. Kopiere den Schlüssel sofort, denn er wird dir nur einmal angezeigt. Die komplette Anleitung findest du in Was kann ich mit der API App in Perspective machen?
Führe perspective auth login --method api-key aus und füge den Schlüssel ein, wenn das Terminal danach fragt. Deine Eingabe bleibt dabei unsichtbar, und die CLI prüft den Schlüssel mit einer Test-Anfrage, bevor sie ihn speichert.

Nur Account-Admins können API-Schlüssel erstellen. Die Berechtigungen des Schlüssels entscheiden, welche Befehle funktionieren: crm:read und crm:write decken die Kontakt-Befehle ab, metrics:read die Metrik-Befehle.

Für CI-Jobs sparst du dir die Anmeldung und setzt den Schlüssel stattdessen als Umgebungsvariable: export PERSPECTIVE_API_KEY=dein_key.

Mehr zur CLI-Authentifizierung →

Welche Befehle kann ich in Perspective CLI nutzen?

Mit perspective <command> --help siehst du jederzeit die Optionen eines einzelnen Befehls. Das sind die wichtigsten:

Befehl	Was er macht
`perspective funnels list`	Listet alle deine Funnels mit ID, Name und Status auf. Das ist der schnellste Weg, eine Funnel-ID zu finden.
`perspective workspaces list`	Listet deine Workspaces zusammen mit den Funnels darin auf.
`perspective contacts list <funnelId>`	Listet die Kontakte eines Funnels auf, 50 pro Seite. Mit `--all` holst du alle Seiten auf einmal.
`perspective contacts get <funnelId> <contactId>`	Gibt einen einzelnen Kontakt mit allen Feldern zurück.
`perspective contacts create <funnelId>`	Legt einen neuen Kontakt an. Eine E-Mail-Adresse oder eine Telefonnummer ist Pflicht.
`perspective contacts set <funnelId> <contactId> <field> <value>`	Aktualisiert ein einzelnes Feld eines Kontakts, zum Beispiel den Status.
`perspective metrics kpi <funnelId> <subtype>`	Gibt einen KPI zurück, zum Beispiel die Conversion Rate. Mit `all` bekommst du alle KPIs auf einmal.
`perspective metrics chart <funnelId> <subtype>`	Gibt die Daten hinter einem Chart zurück, damit du die Funnel-Performance selbst visualisieren kannst.
`perspective metrics insight <funnelId> <insightId>`	Gibt die Antworten zurück, die Nutzer bei einem Frage-Element in deinem Funnel gegeben haben.
`perspective metrics subtypes`	Listet alle KPI- und Chart-Subtypes auf, die du abfragen kannst.

Alle Metrik-Befehle betrachten standardmäßig die letzten 30 Tage. Nutze --days 7 für einen kürzeren Zeitraum oder --from und --to mit ISO-Datumsangaben für einen exakten.

Zwei Optionen funktionieren bei jedem Befehl. --fields behält nur die Felder, die du angibst, zum Beispiel --fields id,email,status, und --pretty erzwingt eingerücktes JSON, das sich am Bildschirm leichter lesen lässt.

Alle Befehle, Optionen und Standardwerte stehen in der Entwickler-Dokumentation.

Komplette CLI-Befehlsreferenz →

💡 Tipp: Wenn du einen Kontakt anlegst oder änderst, kann das deine Automationen auslösen und echte E-Mails an echte Menschen schicken. Hänge bei contacts create oder contacts set zuerst --dry-run an, dann zeigt dir die CLI genau, was sie senden würde, ohne es zu senden.

Wie lasse ich Claude Code die CLI für mich nutzen?

Führe perspective skill install aus, um den Perspective Agent Skill nach ~/.claude/skills/perspective/ zu installieren. Claude Code kennt dann alle verfügbaren Befehle und weiß, wie es sie sicher einsetzt. Du kannst also in normaler Sprache beschreiben, was du brauchst, statt die Befehle selbst zu schreiben.

Mit --project installierst du den Skill stattdessen in den Ordner .claude/skills/ deines aktuellen Projekts. Das ist praktisch, wenn du ihn über dein Repository mit deinem Team teilen willst.

Danach kannst du zum Beispiel fragen: „Welcher meiner Live-Funnels hatte in den letzten 30 Tagen die beste Conversion Rate?" oder „Exportiere alle Kontakte aus dem Webinar-Funnel nach contacts.csv."

Der Skill weist Claude an, erst einen --dry-run auszuführen und bei dir nachzufragen, bevor es einen Kontakt ändert oder anlegt.

Die Perspective CLI mit AI-Agenten nutzen →

Was mache ich, wenn ein Befehl in Perspective CLI fehlschlägt?

Schau dir den Fehlercode an, den die CLI ausgibt. Jeder Fehler kommt als JSON auf stderr zurück, in der Form {"error": {"code": "forbidden", "message": ..., "hint": ...}}, der Code sagt dir also, was schiefgelaufen ist.

Code	Was er bedeutet	Was du tun kannst
`unauthenticated`	Du bist nicht angemeldet, oder deine Anmeldung ist abgelaufen.	Prüfe mit `perspective auth status`, was gespeichert ist, und melde dich mit `perspective auth login` neu an.
`forbidden`	Dein Plan oder dein Abo deckt den API-Zugriff nicht ab, der Funnel liegt außerhalb deiner Workspaces, oder deinem Schlüssel fehlt die passende Berechtigung.	Lies die Fehlermeldung. "Your company's plan doesn't include the External API" und "User has no active subscription" sind beides Abo-Themen. Sonst prüfe die Funnel-ID mit `perspective funnels list` und die Berechtigungen deines Schlüssels.
`not_found`	Die Funnel- oder Kontakt-ID existiert nicht.	Schlage die ID mit `perspective funnels list` oder `perspective contacts list` neu nach.
`usage`	Eine Option oder ein Argument stimmt nicht.	Mit `perspective <command> --help` siehst du die genauen Optionen.
`rate_limited`	Du hast mehr als 100 Anfragen pro Minute geschickt.	Warte kurz und führe den Befehl erneut aus. Die CLI wiederholt ihn bereits bis zu 3 Mal von selbst.
`network`	Die API war innerhalb von 30 Sekunden nicht erreichbar.	Prüfe deine Internetverbindung und versuche es erneut.

FAQ

Brauche ich Entwickler-Kenntnisse, um die Perspective CLI zu nutzen?

Du solltest dich im Umgang mit einem Terminal wohlfühlen, programmieren musst du aber nicht. Die Installation ist ein Befehl, die Anmeldung ein weiterer, und danach führst du einzelne Befehle wie perspective funnels list aus und bekommst deine Daten als JSON zurück. Wenn du gar nicht mit einem Terminal arbeiten möchtest, kannst du über den Perspective MCP dieselben Daten in normaler Sprache direkt in deinem AI-Agenten abfragen.

Welchen Perspective-Plan brauche ich für die CLI?

Die CLI braucht API-Zugriff, und der ist im Scale Plan und im alten Volume Plan enthalten. Die Pläne Base, Grow und Expand enthalten ihn nicht, die übrigen Legacy-Pläne ebenfalls nicht. Außerdem muss dein Abo aktiv sein, denn die API lehnt ein abgelaufenes Abo auch im Scale oder Volume Plan ab. Ohne API-Zugriff kannst du die CLI zwar installieren und dich anmelden, die Befehle contacts und metrics geben dann aber einen Fehler zurück. Was dein Plan sonst noch enthält, siehst du in Welche Features sind in den Plänen enthalten?

Kann ich mit der CLI Funnels erstellen oder bearbeiten?

Nein, die CLI liest deine Funnels nur aus. Sie kann keinen Funnel anlegen, bearbeiten, veröffentlichen oder löschen. Wenn du einen Funnel mit AI bauen willst, nutze den Perspective MCP in Claude oder ChatGPT, oder erstelle ihn direkt in Perspective. Beide Wege findest du in Wie erstelle ich einen Funnel mit AI?

Was ist der Unterschied zwischen der Perspective CLI und dem Perspective MCP?

Die CLI ist ein Terminal-Tool zum Lesen und Aktualisieren von Daten und eignet sich damit gut für Skripte, Exporte, geplante Jobs und Reporting. Der MCP verbindet Perspective mit einem AI-Assistenten wie Claude oder ChatGPT und kann zusätzlich Funnels bauen sowie E-Mail-Sequenzen und Brands verwalten. Viele nutzen beides: den MCP zum Bauen und die CLI, um Daten abzuholen.

Brauche ich einen API-Schlüssel, um die Perspective CLI zu nutzen?

Auf deinem eigenen Rechner nicht. Wenn du perspective auth login im Terminal ausführst, öffnet sich dein Browser und du meldest dich direkt bei Perspective an, ohne jemals einen Schlüssel anzufassen. Einen API-Schlüssel brauchst du nur für Dinge, die ohne dich laufen, also ein Skript, einen Server oder einen CI-Job, oder wenn sich dein Team einen Schlüssel teilen soll. Diese Schlüssel können ausschließlich Account-Admins erstellen. In beiden Fällen landen deine Zugangsdaten in ~/.config/perspective/credentials.json, lesbar nur für dich, und perspective auth logout löscht sie wieder.

Warum bekomme ich einen "forbidden"-Fehler bei einem Funnel, den ich in Perspective sehen kann?

Die Fehlermeldung sagt dir, woran es liegt. "Your company's plan doesn't include the External API" bedeutet, dass du den Scale Plan oder den alten Volume Plan brauchst. "User has no active subscription" bedeutet, dass dein Plan passt, dein Abo aber abgelaufen ist. Dann lohnt sich ein Blick in deine Rechnungsdaten. Jeder andere forbidden-Fehler heißt meistens, dass dein API-Schlüssel den Workspace dieses Funnels nicht abdeckt oder ihm die nötige Berechtigung fehlt. Prüfe dann den Workspace-Zugriff und die Datenberechtigungen, die du beim Erstellen des Schlüssels gesetzt hast. Mit perspective funnels list siehst du, welche Funnels du erreichst.