Vonage CLI Version 3 ist jetzt allgemein verfügbar

Achtung, ihr Tölpel! Eine neue Vonage CLI hat die Segel gesetzt! Die vorherige Version? Nun, die ist über die Planke gegangen und ruht nun in Davy Jones' Spind. Diese Geschichte beschreibt die tückischen Gewässer, die wir für den Wechsel durchquert haben, die vielen Änderungen, die wir entdeckt haben, und wie diese große Überholung die Vonage CLI zu einem mächtigeren Schiff macht - leichter zu segeln, schneller zu bedienen und bereit für Anfänger und Seebären gleichermaßen!

Ok, warum spreche ich wie ein Pirat? Weil die Version 3 der Vonage CLI hier ist, sie wurde von Grund auf neu geschrieben und verwendet das Piraten-Thema yargs Framework. In diesem Beitrag werde ich darauf eingehen, warum wir die Umstellung vorgenommen haben, was sich geändert hat und wie diese Überarbeitung die CLI einfacher, flexibler und leistungsfähiger macht, sowohl für neue Benutzer als auch für erfahrene Profis.

Warum die neue Version?

Frühere Versionen verwendeten oclif. Während oclif ein großartiges Framework ist, stieß die Vonage CLI an ihre Grenzen. Yargs bietet ein einfaches Framework, bei dem Sie nur eine Handler-Funktion erstellen müssen, die die geparsten Befehlszeilenargumente akzeptiert. Dies erleichtert das Testen, da nur die erwarteten Argumente übergeben und die Ausgabe validiert werden muss. Yargs kümmert sich nur um eine Sache, nämlich das Parsen der Argumente. Oclif kümmert sich um die Argumente, führt die Befehle aus, analysiert die Ausgabe und kontrolliert die Benutzererfahrung. In früheren Versionen war das oclif-Plugin-System verlockend, da wir Beta-Befehle hinzufügen konnten, ohne die Kernbefehle zu beeinflussen. Es erwies sich jedoch als verwirrend, da einige Benutzer die Installation dieses Befehls übersehen haben könnten, was zu der Annahme führte, dass ein Fehler in der CLI vorlag. Es erwies sich auch als schwierig, die Standards in den Plugins zu befolgen, was dazu führte, dass einige Befehle den Befehl --api-key, --apiSchlüssel oder --api_schlüssel.

Wir mussten von vorne anfangen und einen pragmatischen Ansatz für die Befehlszeilenschnittstelle wählen. Bei jedem Befehl haben wir uns gefragt: "Wer wird diesen Befehl verwenden und wofür wird er verwendet? Bei der Beantwortung der Frage nach dem "Wer" wollten wir die Befehlszeilenschnittstelle sowohl für neue Benutzer (diejenigen, die noch nie CLI-Programme verwendet haben, und diejenigen, die Vonage noch nie benutzt haben) als auch für Superuser einfach gestalten. Jeder Befehl kann JSON oder YAML ausgeben, was die Skripterstellung für die Superuser und den reinen Text für diejenigen, die noch nie mit Vonage gearbeitet haben, erleichtert. Wir wollten auch versuchen, die neue CLI so zugänglich wie möglich zu machen. Wir haben versucht, diesen Idealen als Teil von Ericsson (einem schwedischen Unternehmen) zu folgen.

Lassen Sie uns also in die Version 3 der Vonage CLI eintauchen.

Installieren Sie

Vor der Installation müssen Sie über NodeJS installiert haben (Version 18 oder höher). Sobald Sie das haben, können Sie es mit npm:

npm install -g @vonage/cli

Dadurch wird die vonage Befehl systemweit für Ihren Benutzer verfügbar. Das war's schon. Sie können nun die CLI verwenden. Aber... Sie müssen Ihre Vonage-Anmeldedaten jedes Mal eingeben, wenn Sie einen Befehl ausführen. Eine Anleitung zur Konfiguration der CLI finden Sie weiter unten.

Automatische Aktualisierungen

V3 enthält auch automatische Aktualisierungsfunktionen. Wenn Sie einen Befehl ausführen, kontaktiert die CLI NPM, um nach einer neuen Version zu suchen (dies geschieht nur einmal täglich). Wenn eine neue Version veröffentlicht wurde, wird nach Beendigung der Befehlsausführung eine entsprechende Meldung ausgegeben. In Ihrem Home-Verzeichnis wird eine Datei mit der Bezeichnung .vonage erstellt, die das letzte Mal, als die Prüfung durchgeführt wurde, und die neueste Version enthält.

Hinweis: Wenn eine kritische Aktualisierung vorliegt, funktioniert die Befehlszeilenschnittstelle nicht, bis Sie die Aktualisierung durchgeführt haben.

Konfiguration

Das Konfigurationssystem in älteren Versionen war verwirrend. Es gab die vonage.json Datei im aktuellen Arbeitsverzeichnis, Umgebungsvariablen, übergebene Argumente und eine globale Konfigurationsdatei. Da jeder Ort unterschiedliche Werte enthalten konnte, konnte die Ausführung eines Befehls unerwünschte Auswirkungen haben. Also haben wir es einfach gemacht. Die Authentifizierungsparameter folgen dieser Hierarchie: An den Befehl übergebene Argumente -> eine lokale .vonagerc Datei -> eine globale config.json Datei, die sich in $HOME/.vonage. Die Werte würden auch über die verschiedenen Ebenen hinweg zusammengeführt. Angenommen, Sie hätten einen lokal konfigurierten privaten Schlüssel und eine global konfigurierte Anwendungs-ID. In diesem Fall können Sie sich möglicherweise nicht korrekt authentifizieren, da die Anwendungs-ID nicht mit dem privaten Schlüssel gepaart ist.

V3 hat die Konfiguration vereinfacht. Die Konfigurationswerte werden nicht mehr zusammengeführt. Stattdessen lädt die CLI die Konfiguration in der folgenden Reihenfolge:

1. Befehlszeilen-Flags --api-key, --api-geheimnis, --private-key, und --app-id.

2. Eine lokale Konfigurationsdatei im aktuellen Arbeitsverzeichnis .vonagerc.

3. Eine globale Konfigurationsdatei in der Datei .vonage Ordner in Ihrem Heimatverzeichnis $HOME/.vonage/config.json.

So speichern Sie Ihre Anmeldedaten mit vonage auth set:

vonage auth set --api-key=<your api key> --api-secret=<your api secret>

Dadurch werden der API-Schlüssel und das Geheimnis festgelegt und anschließend die Gültigkeit der Einstellungen bestätigt:

✅ Checking API Key Secret

API Key: <Your api key>
API Secret: **************

Profi-Tipp: Verwenden Sie --local wenn Sie diese Einstellungen nur in dem Verzeichnis speichern wollen, in dem Sie sich gerade befinden.

Ihre Anmeldedaten sind nun gespeichert in <Ihr Heimatverzeichnis>/.vonage/config.json. Später, wenn Sie vergessen haben, was Sie eingestellt haben, vonage auth show die Authentifizierungseinstellungen ausgeben (und überprüfen).

Tipp: Fügen Sie --show-all wenn Sie nicht-redigierte Werte sehen wollen.

vonage auth show

Global credentials found at: /Users/manchuck/.vonage/config.json

API Key: 76009afe
API Secret: dWB**************

✅ Checking API Key Secret

Einige Befehle funktionieren nur mit einer Vonage Anwendung. Sie können die Anwendungseinstellungen mit --app-id und --private-key

Hinweis: Sie müssen auch den --api-Schlüssel und --api-geheimnis.

API Key: 76009afe
API Secret: dWB**************
App ID: 4f4d4831-1491-41d4-be82-689c78e09997
Private Key: Is Set

✅ Checking API Key Secret
✅ Checking App ID and Private Key

Jetzt können Sie die Befehlszeilenschnittstelle verwenden, ohne bei jedem Aufruf die Anmeldeinformationen eingeben zu müssen.

Verwendung

Ich werde nicht auf alle Befehle eingehen (sie sind zahlreich, und wir fügen ständig neue hinzu), aber Sie können den Befehl --help Flag verwenden, um alle verfügbaren Befehle und ihre Verwendung zu sehen. Ich werde zwei wertvolle Gruppen hervorheben.

JWT-Befehle

Es gibt zwei JWT-Befehle: vonage jwt create, und vonage jwt validieren. (Wir verwenden den Befehl create in unseren cURL-Codeschnipseln). Validate kann hilfreich sein, wenn bei API-Aufrufen Probleme mit der Authentifizierung auftreten. Da wir die CLI im vorigen Abschnitt konfiguriert haben, kann der Befehl vonage jwt create diese Anmeldedaten verwenden:

vonage jwt create
... A created JWT token is outputted ...

Sie können auch in einer ACL einen Betreff und eine eigene Ablaufzeit festlegen:

vonage jwt create \
--app-id='00000000-0000-0000-0000-000000000000' \
--private-key=./private.key \
--sub='Alice' \
--acl='{"paths":{"/*/rtc/**":{},"/*/users/**":{},"/*/conversations/**":{},"/*/sessions/**":{},"/*/devices/**":{},"/*/image/**":{},"/*/media/**":{},"/*/applications/**":{},"/*/push/**":{},"/*/knocking/**":{},"/*/legs/**":{}}}' \
--exp=872827200

... A created JWT token is outputted ...

Tipp: Unter MacOS kann der Befehl pbcopy Befehl einen Befehl in die Zwischenablage ausgeben. Dies geschieht durch Hinzufügen einer Pipe nach dem Befehl vonage jwt create | pbcopy.

Der Befehl validate kann überprüfen, ob das Token korrekt für Ihre Anwendung signiert ist, er kann aber auch die anderen Ansprüche überprüfen:

vonage jwt create <JWT Token> \
--app-id='00000000-0000-0000-0000-000000000000' \
--private-key=./private.key \
--sub='Alice' \
--acl='{"paths":{"/*/rtc/**":{},"/*/users/**":{},"/*/conversations/**":{},"/*/sessions/**":{},"/*/devices/**":{},"/*/image/**":{},"/*/media/**":{},"/*/applications/**":{},"/*/push/**":{},"/*/knocking/**":{},"/*/legs/**":{}}}' \
--exp=872827200

✅ Token was signed with the correct private key
✅ Token has not expired
✅ Application Id [00000000-0000-0000-0000-000000000000] matches [00000000-0000-0000-0000-000000000000]
✅ Subject [Alice] matches [Alice]
✅ ACL matches
  ✅ [ANY]  /*/rtc/**
  ✅ [ANY]  /*/users/**
  ✅ [ANY]  /*/conversations/**
  ✅ [ANY]  /*/sessions/**
  ✅ [ANY]  /*/devices/**
  ✅ [ANY]  /*/image/**
  ✅ [ANY]  /*/media/**
  ✅ [ANY]  /*/applications/**
  ✅ [ANY]  /*/push/**
  ✅ [ANY]  /*/knocking/**
  ✅ [ANY]  /*/legs/**
✅ All checks complete! Token is valid

Anwendungsbefehle

Ich möchte Folgendes hervorheben vonage-Anwendungen hervorheben, da sie am häufigsten verwendet werden und sich in dieser Version erheblich verändert haben. Die wichtigste Änderung betrifft die Erstellung von Applications. In der Vorgängerversion konnten Sie die Anwendung erstellen und gleichzeitig alle Einstellungen für die Funktionen vornehmen. In V3 wird dies in zwei separate Befehle aufgeteilt. Da wir unsere Produktlinien erweitert haben, ist die Anzahl der Flags, die zur Konfiguration all dieser Fähigkeiten benötigt werden, gestiegen. Außerdem mussten Sie, wenn Sie eine kleine Änderung an einer Fähigkeit vornehmen wollten, die gesamte Konfiguration übergeben oder riskieren, dass nicht zusammenhängende Fähigkeiten geändert werden. Im Folgenden wird erläutert, wie Sie eine Anwendung einrichten, für die Nachrichten- und Verify-Funktionen konfiguriert sind.

Beginnen Sie mit der Erstellung einer neuen Anwendung:

vonage apps create "My Vonage Application"

✅ Creating Application
✅ Saving private key
Application created

Name: My Vonage Application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  None Enabled

Hinweis: Für diejenigen, die mit V1 vertraut sind, generiert die Befehlszeilenschnittstelle keinen Namen mehr für Ihre Anwendung; Sie müssen einen Namen angeben.

Als nächstes konfigurieren wir Nachrichten mit vonage apps capabilities update <Anwendungskennung> messages:

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 messages \
--messages-inbound-url='https://example.com/messages/inboud' \
--messages-status-url='https://example.com/messages/status \
--messages-version='v1' \
--no-messages-authenticate-media

✅ Fetching Application
✅ Adding messages capability to application: My Vonage Application

Name: My Vonage Application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  MESSAGES:
	Authenticate Inbound Media: Off
	Webhook Version: v1
	Status URL: [POST] https://example.com/messages/status
	Inbound URL: [POST] https://example.com/messages/inboud

Und jetzt fügen wir Verify hinzu, indem wir einfach die Nachrichten in verify:

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 verify \
--verify-status-url='https://example.com/verify'

✅ Fetching Application
✅ Adding verify capability to application: My Vonage Application

Name: My Vonage Application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  MESSAGES:
	Authenticate Inbound Media: Off
	Webhook Version: v1
	Status URL: [POST] https://example.com/messages/status
	Inbound URL: [POST] https://example.com/messages/inboud

  VERIFY:
	Webhook Version: v2
	Status URL: https://example.com/verify

Tipp: Wenn Sie einen Wert (z. B. die Status-URL von Nachrichten) zurücksetzen möchten, können Sie in entfernen als Wert übergeben: --messages-status-url='__remove__'.

Abschließende Bemerkungen

Die Verwendung einer Befehlszeilenschnittstelle (CLI) im Jahr 2025 mag sich veraltet anfühlen, aber vielleicht möchten Sie die Anmeldedaten für das Dashboard nicht mit allen Mitarbeitern Ihres Unternehmens teilen. Unser Subaccounts API ermöglicht es Ihnen, isolierte Accounts mit eigenen API-Schlüsseln und -Geheimnissen zu erstellen. CLI-Programme helfen auch bei der Automatisierung von Prozessen. Erstellen Sie eine Testanwendung von Vonage für Ihre Staging-Umgebung, damit Sie sicher sein können, dass Ihr Code mit den Vonage-Diensten funktioniert. (Halten Sie Ausschau nach vonage verify um MFA einfach hinzuzufügen).

Wir sind noch nicht fertig damit, der CLI neue Befehle und Funktionen hinzuzufügen. Verwenden Sie --help um alle verfügbaren Befehle und deren Verwendung anzuzeigen. Sie können auch unsere Seite "Erste Schritte mit Vonage CLI" lesen Seite oder das GitHub Repository