A versão 3 do CLI da Vonage já está disponível para o público em geral

Atenção, malandros! Uma nova CLI da Vonage zarpou! A versão anterior? Bem, ela foi jogada pela prancha e agora repousa no fundo do mar. Esta história aqui narra as águas traiçoeiras que enfrentamos para fazer a mudança, a abundância de novidades que descobrimos e como essa grande reformulação torna a CLI da Vonage uma embarcação mais poderosa — mais suave de navegar, mais ágil de comandar e pronta tanto para novatos quanto para lobos do mar experientes!

Ok, por que estou falando como um pirata? Porque a versão 3 da CLI da Vonage já chegou; ela foi totalmente reescrita do zero usando o yargs . Nesta postagem, vou explicar por que fizemos essa mudança, o que mudou e como essa reformulação torna a CLI mais fácil de usar, mais flexível e mais poderosa, tanto para novos usuários quanto para profissionais experientes.

Por que essa nova versão?

As versões anteriores usavam oclif. Embora o oclif seja uma excelente estrutura, a CLI da Vonage estava atingindo seus limites. O Yargs oferece uma estrutura simples, na qual basta criar uma função de tratamento que aceite os argumentos da linha de comando já analisados. Isso facilita os testes, exigindo apenas a passagem dos argumentos esperados e a validação da saída. O Yargs lida com apenas uma coisa: a análise dos argumentos. O oclif lida com os argumentos, executa comandos, analisa a saída e controla a experiência do usuário. Nas versões anteriores, era tentador usar o sistema de plug-ins do oclif, pois podíamos adicionar comandos em fase beta sem afetar os comandos principais. No entanto, isso se mostrou confuso, pois alguns usuários poderiam ter esquecido de instalar aquele comando, levando à crença de que havia um bug na CLI. Também foi um desafio seguir os padrões nos plug-ins, levando a casos em que alguns comandos aceitavam --api-key, --apiKey ou --api_key. 

Precisávamos recomeçar do zero e adotar uma abordagem pragmática em relação à CLI. A cada comando, nos perguntávamos: “Quem vai usar isso e para que vai servir?”. Ao tentar responder à parte do “quem”, queríamos tornar a CLI fácil tanto para novos usuários (aqueles que estão começando a usar programas de CLI e aqueles que nunca usaram o Vonage antes) quanto para superusuários. Cada comando pode gerar resultados em JSON ou YAML, facilitando a criação de scripts para os superusuários e oferecendo texto simples para quem está começando a usar o Vonage. Também queríamos tentar tornar a nova CLI o mais acessível possível. Tentamos seguir esses ideais como parte da Ericsson (uma empresa com sede na Suécia). 

Dito isso, vamos nos aprofundar na Versão 3 da CLI da Vonage.

Instalar

Antes da instalação, é necessário ter o NodeJS instalado (versão 18 ou superior). Depois de fazer isso, você pode instalá-lo usando o npm:

npm install -g @vonage/cli

Isso fará com que o vonage estará disponível em todo o sistema para o seu usuário. É só isso. Você está pronto para começar a usar a CLI. Mas… você precisa inserir suas credenciais da Vonage toda vez que executar um comando. Veja abaixo as instruções para configurar a CLI.

Atualizações automáticas

A V3 também inclui recursos de atualização automática. Quando você executa um comando, a CLI entra em contato com o NPM para verificar se há uma nova versão (isso ocorre apenas uma vez por dia). Se uma nova versão tiver sido lançada, você verá uma mensagem exibida após a conclusão da execução do comando. Um arquivo é criado no seu diretório home, na pasta pasta .vonage , contendo a data e hora da última verificação e a versão mais recente. 

Observação: Se houver uma atualização crítica, a CLI não funcionará até que você faça a atualização.

Configuração

O sistema de configuração nas versões anteriores era confuso. Havia o arquivo arquivo vonage.json no diretório de trabalho atual, variáveis de ambiente, argumentos passados e um arquivo de configuração global. Como cada um desses locais podia conter valores diferentes, a execução de um comando poderia causar efeitos indesejáveis. Por isso, simplificamos tudo. Os parâmetros de autenticação seguem esta hierarquia: Argumentos passados ao comando -> um arquivo local .vonagerc local -> um arquivo de configuração global config.json localizado em $HOME/.vonage. Os valores também seriam mesclados entre as diferentes camadas. Suponha que você tenha uma chave privada configurada localmente e um ID de aplicativo configurado globalmente. Nesse caso, talvez você não consiga se autenticar corretamente, pois o ID de aplicativo não está emparelhado com a chave privada.

A versão V3 simplificou a configuração. Os valores de configuração não serão mais mesclados. Em vez disso, a CLI carregará a configuração na seguinte ordem:

1. Opções de linha de comando --api-key, --api-secret, --private-keye --app-id.

2. Um arquivo de configuração local no diretório de trabalho atual .vonagerc.

3. Um arquivo de configuração global na pasta pasta .vonage no seu diretório pessoal $HOME/.vonage/config.json.

Veja a seguir como salvar suas credenciais usando o conjunto de autenticação da Vonage:

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

Isso definirá a chave da API e o segredo e, em seguida, confirmará se as configurações estão corretas:

✅ Checking API Key Secret

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

Dica profissional: Use --local se quiser salvar essas configurações apenas no diretório em que você está no momento.

Suas credenciais estão agora salvas em <Seu diretório pessoal>/.vonage/config.json. Mais tarde, caso você esqueça o que configurou, o comando `vonage auth show` exibirá (e verificará) as configurações de autenticação. 

Dica: Adicione --show-all se quiser ver os valores não ocultados.

vonage auth show

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

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

✅ Checking API Key Secret

Alguns comandos só funcionarão com um aplicativo da Vonage aplicativo. Você pode definir as configurações do aplicativo usando --app-id e --private-key

Observação: você também precisará fornecer a --api-key e --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

Agora, você pode usar a CLI sem precisar fornecer credenciais a cada chamada. 

Uso

Embora eu não vá abordar todos os comandos (são muitos, e estamos sempre adicionando novos), você pode usar o --help em qualquer lugar para ver todos os comandos disponíveis e como usá-los. Vou destacar dois grupos importantes.

Comandos JWT

Existem dois comandos JWT: vonage jwt create, e vonage jwt validate. (Usamos o comando create em nossos trechos de código do cURL). O comando `validate` pode ser útil caso você encontre problemas de autenticação ao fazer chamadas de API. Agora, como configuramos a CLI na seção anterior, execute vonage jwt create usará essas credenciais:

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

Você também pode, em uma ACL, definir um prazo de validade 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 ...

Dica: No macOS, o comando comando copiará um comando para a sua área de transferência. Isso é feito adicionando um barra vertical após o comando vonage jwt create | pbcopy.

O comando `validate` pode verificar se o token está corretamente assinado para o seu aplicativo, mas também pode verificar as outras reivindicações:

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 do aplicativo

Gostaria de destacar os aplicativos da Vonage , já que são os mais utilizados e sofreram mudanças significativas nesta versão. A principal mudança diz respeito à criação de Applications. A versão anterior permitia criar o Application e definir todas as configurações de recursos simultaneamente. A V3 divide isso em dois comandos separados. À medida que expandimos nossas linhas de produtos, o número de parâmetros necessários para configurar todos esses recursos aumentou. Além disso, se você quisesse fazer uma pequena alteração em um recurso, teria que passar toda a configuração ou correr o risco de alterar recursos não relacionados. Vamos ver passo a passo como configurar um aplicativo que tenha mensagens e recursos de Verify configurados.

Comece criando um novo aplicativo:

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

Observação: Para quem está familiarizado com a V1, a CLI não gerará mais um nome para o seu aplicativo; você deverá especificar um.

A seguir, vamos configurar as mensagens usando vonage apps capabilities update <ID do aplicativo> 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

E agora vamos adicionar Verify simplesmente alterando mensagens para 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

Dica: Se você quiser desativar um valor (por exemplo, a URL de status das mensagens), pode passar remove como valor: --messages-status-url=’__remove__’.

Considerações finais

Usar uma CLI em 2025 pode parecer ultrapassado, mas talvez você não queira compartilhar as credenciais do painel com todos na sua organização. Nossa API de Subaccounts permite que você crie contas isoladas com suas próprias chaves e segredos de API. Os programas de CLI também auxiliam nos processos de automação. Crie um aplicativo de teste da Vonage para seu ambiente de teste a fim de ter certeza de que seu código funcionará com os serviços da Vonage. (Fique de olho no o Vonage Verify , que em breve permitirá adicionar a autenticação multifatorial (MFA) com facilidade).

Ainda não terminamos de adicionar novos comandos e recursos à CLI. Use --help em qualquer lugar para ver todos os comandos disponíveis e como usá-los. Você também pode conferir nossa página “Introdução à CLI da Vonage” página ou o repositório do GitHub no GitHub