La versión 3 de la CLI de Vonage ya está disponible en general

¡Avast Ye Scallywags! ¡Una nueva CLI de Vonage ha zarpado! ¿La versión anterior? Bueno, caminó por la plancha y ahora descansa en el armario de Davy Jones. Esta historia describe las traicioneras aguas que desafiamos para hacer el cambio, la gran cantidad de cambios que descubrimos y cómo esta gran revisión convierte a la CLI de Vonage en una nave más poderosa: ¡más fácil de navegar, más rápida de comandar y lista para novatos y lobos de mar salados por igual!

Ok, ¿por qué estoy hablando como un pirata? Porque ya está aquí la versión 3 de la CLI de Vonage, que ha sido completamente reescrita desde cero utilizando la tecnología pirata yargs de temática pirata. En este post voy a explicar por qué hicimos el cambio, lo que ha cambiado, y cómo esta revisión hace que la CLI sea más fácil de usar, más flexible y más potente tanto para los nuevos usuarios como para los profesionales experimentados.

¿Por qué la nueva versión?

Las versiones anteriores utilizaban oclif. Mientras que oclif es un gran marco, la CLI de Vonage estaba golpeando sus limitaciones. Yargs proporciona un marco simple en el que sólo tienes que crear una función de controlador que acepte los argumentos de línea de comandos analizados. Esto facilita las pruebas al requerir que se pasen los argumentos esperados y se valide la salida. Yargs sólo se encarga de una cosa: analizar los argumentos. Oclif maneja los argumentos, ejecuta los comandos, analiza la salida y controla la experiencia del usuario. En versiones anteriores, el sistema de plugins de oclif era tentador de usar, ya que podemos añadir comandos beta sin afectar a los comandos principales. Sin embargo, resultaba confuso, ya que algunos usuarios podían no haber instalado ese comando, lo que hacía pensar que había un error en la CLI. También demostró ser un reto seguir los estándares en los plugins, dando lugar a casos en los que algunos comandos aceptaban --api-clave, --apiKey o --api_key.

Necesitábamos empezar de nuevo y adoptar un enfoque pragmático de la CLI. Con cada comando, nos preguntamos: "¿Quién usará esto y para qué lo usará?". Al buscar una respuesta a la parte de "quién", queríamos que la CLI fuera fácil para los nuevos usuarios (aquellos que recién comienzan a usar programas de CLI y aquellos que nunca antes usaron Vonage) y los superusuarios. Todos los comandos pueden generar JSON o YAML, lo que facilita la creación de scripts para los superusuarios y texto sin formato para los nuevos usuarios de Vonage. También queríamos intentar que la nueva CLI fuera lo más accesible posible. Intentamos seguir esos ideales como parte de Ericsson (una empresa con sede en Suecia).

Dicho esto, vamos a sumergirnos en la versión 3 de la CLI de Vonage.

Instale

Antes de instalar, debe tener NodeJS instalado (versión 18 o superior). Una vez que lo tengas, puedes instalarlo usando npm:

npm install -g @vonage/cli

Esto hará que vonage disponible en todo el sistema para su usuario. Eso es todo. Estás listo para comenzar a usar la CLI. Pero... debes ingresar tus credenciales de Vonage cada vez que ejecutes un comando. Consulta a continuación las instrucciones para configurar la CLI.

Actualizaciones automáticas

V3 también incluye funciones de actualización automática. Cuando se ejecuta un comando, la CLI se pone en contacto con NPM para comprobar si hay una nueva versión (esto sólo se ejecuta una vez al día). Si se ha publicado una nueva versión, verás un mensaje impreso después de que el comando termine de ejecutarse. Se crea un archivo en tu directorio home en el directorio .vonage que contiene la última vez que se realizó la comprobación y la última versión.

Nota: Si hay una actualización crítica, la CLI no funcionará hasta que se actualice.

Configuración

El sistema de configuración de las versiones anteriores era confuso. Existía el archivo vonage.json en el directorio de trabajo actual, variables de entorno, argumentos pasados y un archivo de configuración global. Dado que cada lugar podía contener diferentes valores, ejecutar un comando podía causar efectos no deseados. Así que lo hemos simplificado. Los parámetros de autenticación siguen esta jerarquía Argumentos pasados al comando -> un archivo local .vonagerc local -> un archivo config.json global ubicado en $HOME/.vonage. Los valores también se fusionarían a través de las diferentes capas. Supongamos que tienes una clave privada configurada localmente y un ID de aplicación configurado globalmente. En ese caso, es posible que no puedas autenticarte correctamente ya que el ID de la aplicación no está emparejado con la clave privada.

La V3 ha simplificado la configuración. Ya no se fusionarán los valores de configuración. En su lugar, la CLI cargará la configuración en el siguiente orden:

1. Banderas de línea de comandos --api-clave, --api-secret, --clave-privaday --app-id.

2. Un archivo de configuración local en el directorio de trabajo actual .vonagerc.

3. Un archivo de configuración global en el directorio .vonage en su directorio personal $HOME/.vonage/config.json.

A continuación se explica cómo guardar las credenciales mediante vonage auth set:

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

Esto establecerá la clave y el secreto de la API y, a continuación, confirmará que la configuración es válida:

✅ Checking API Key Secret

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

Consejo profesional: Utilice --local si sólo desea guardar estos ajustes en el directorio en el que se encuentra actualmente.

Sus credenciales se guardan ahora en <Su directorio personal>/.vonage/config.json. Más tarde, si olvida lo que ha configurado, vonage auth show mostrará (y comprobará) la configuración de autenticación.

Consejo: Añada --show-all si desea ver los valores no censurados.

vonage auth show

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

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

✅ Checking API Key Secret

Algunos comandos sólo funcionarán contra una aplicación de Vonage de Vonage. Puedes establecer la configuración de la aplicación usando --app-id y --clave-privada

Nota: También tendrá que proporcionar la --api-clave y --api-secret.

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

Ahora puede utilizar la CLI sin necesidad de introducir credenciales en cada llamada.

Utilización

Aunque no voy a repasar todos los comandos (son numerosos y añadimos más constantemente), puede utilizar el comando --help en cualquier lugar para ver todos los comandos disponibles y cómo utilizarlos. Destacaré dos grupos valiosos.

Comandos JWT

Hay dos comandos JWT: vonage jwt create y vonage jwt validate. (Utilizamos el comando create en nuestros fragmentos de código cURL). Validate puede ser útil si te encuentras con problemas de autenticación al realizar llamadas a la API. Ahora, ya que hemos configurado la CLI en la sección anterior, ejecutando vonage jwt create usará esas credenciales:

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

También puede, en una ACL, asignar y establecer un tiempo de expiración personalizado:

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 ...

Consejo: En MacOS, la función pbcopy mostrará un comando en el portapapeles. Esto se hace añadiendo una tubería después del comando vonage jwt create | pbcopy.

El comando validar puede comprobar que el token está correctamente firmado en tu aplicación, pero también puede comprobar las otras reclamaciones:

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

Comandos de aplicación

Quiero destacar aplicaciones vonage ya que son las más utilizadas y han cambiado significativamente en esta versión. El principal cambio se produce en la creación de aplicaciones. La versión anterior te permitía crear la aplicación y establecer todos los ajustes de capacidad simultáneamente. La V3 divide esto en dos comandos separados. Como hemos ampliado nuestras líneas de productos, el número de banderas necesarias para configurar todas estas capacidades ha crecido. Además, si quisieras hacer un pequeño cambio en una capacidad, tendrías que pasar toda la configuración o arriesgarte a cambiar capacidades no relacionadas. Veamos cómo configurar una aplicación que tenga configuradas las funciones de mensajes y Verify.

Empiece por crear una nueva aplicación:

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

Nota: Para aquellos familiarizados con la V1, la CLI ya no generará un nombre para su aplicación; debe especificar uno.

A continuación, configuraremos los mensajes utilizando vonage apps capabilities update <id de aplicación> mensajes:

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

Y ahora añadimos Verify con sólo cambiar mensajes a verificar:

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

Sugerencia: Si desea eliminar un valor (por ejemplo, la URL de estado de los mensajes), puede pasar el parámetro eliminar como valor: --messages-status-url='__remove__'.

Comentarios finales

Utilizar una CLI en 2025 puede parecer anticuado, pero es posible que no desee compartir las credenciales del panel de control con todos los miembros de su organización. Nuestra API de Subaccounts le permite crear cuentas aisladas con sus Claves y Secretos API. Los programas CLI también ayudan con los procesos de automatización. Crea una aplicación de Vonage de prueba para tu entorno de ensayo para que tengas la confianza de que tu código funcionará con los servicios de Vonage. (No pierdas de vista Vonage Verify que pronto agregará MFA fácilmente).

No hemos terminado de añadir nuevos comandos y funciones a la CLI. Utilice --help en cualquier lugar para ver todos los comandos disponibles y cómo usarlos. También puedes consultar nuestra página "Primeros pasos con la CLI de Vonage". página o el repositorio repositorio