Avast Ye Scallywags! A new Vonage CLI has set sail! The previous version? Well, it walked the plank and now rests in Davy Jones’ locker. This here tale charts the treacherous waters we braved to make the switch, the bounty of changes we unearthed, and how this grand overhaul makes the Vonage CLI a mightier vessel—smoother to sail, swifter to command, and ready for both greenhorns and salty sea dogs alike!

Ok, why am I speaking like a pirate? Because version 3 of the Vonage CLI is here, it has been completely rewritten from the ground up using the pirate-themed yargs framework. In this post I will go into why we made the switch, what’s changed, and how this overhaul makes the CLI easier to use, more flexible, and more powerful for both new users and seasoned pros.

Why the New Version?

Previous versions used oclif. While oclif is a great framework, the Vonage CLI was hitting its limitations. Yargs provides a simple framework where you only need to create a handler function that accepts the parsed command line arguments. This makes testing easy by requiring passing in the expected arguments and validating output. Yargs handles one thing only, and that is parsing the arguments. Oclif handles the arguments, executes commands, parses output, and controls the user experience. In previous versions, the oclif plugin system was tempting to use as we can add in beta commands without impacting the core commands. However, it proved confusing as some users might have missed installing that command, leading to the belief that there was a bug in the CLI. It also proved challenging following standards in the plugins, leading to instances where some commands accepted --api-key, --apiKey or --api_key. 

We needed to start over and take a pragmatic approach to the CLI. With each command, we asked, “Who will use this, and what will they use it for?”. When looking to answer the “who” part, we wanted to make the CLI easy for new users (those new to using CLI programs and those who have never used Vonage before) and super users. Every command can output JSON or YAML, allowing for easier scripting for the super users and plain text for those new to Vonage. We also wanted to take a stab at making the new CLI as accessible as possible. We tried to follow those ideals as a part of Ericsson (a Swedish-based company). 

That said, let us dive into Version 3 of the Vonage CLI.

Install

Before installing, you must have NodeJS installed (version 18 or greater). Once you have that, you can install it using npm:

npm install -g @vonage/cli

This will make the vonage command available system-wide for your user. That's all there is to it. You are ready to start using the CLI. But… you must pass in your Vonage credentials every time you run a command. See below for instructions on configuring the CLI.

Automatic Updates

V3 also includes automatic update features. When you run a command, the CLI contacts NPM to check for a new version (this only runs once a day). If a new version has been released, you will see a message printed out after the command finishes execution. A file in your home directory is created in the .vonage folder containing the last time the check was made and the latest version. 

Note: If there is a critical update, the CLI will not function until you update.

Configuration

The configuration system in older versions was confusing. There was the vonage.json file in the currently working directory, environment variables, arguments passed in, and a global configuration file. Since each place could hold different values, running a command could cause undesirable effects. So, we made it simple. The authentication parameters follow this hierarchy: Arguments passed into the command -> a local .vonagerc file -> a global config.json file located in $HOME/.vonage. Values would also merge across the different layers. Suppose you had a private key configured locally and an application ID configured globally. In that case, you might not be able to authenticate correctly since the application ID is not paired with the private key.

V3 has simplified the configuration. No longer will configuration values be merged. Instead, the CLI will load the configuration in the following order:

1. Command line flags --api-key, --api-secret, --private-key, and --app-id.

2. A local configuration file in the current working directory .vonagerc.

3. A global configuration file in the .vonage folder in your home directory $HOME/.vonage/config.json.

Here is how to save your credentials using vonage auth set:

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

This will set the API key and Secret, then confirm the settings are valid:

✅ Checking API Key Secret

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

Pro Tip: Use --local if you only want to save these settings in the directory you currently are in.

Your credentials are now saved to <Your home directory>/.vonage/config.json. Later on, if you forget what you have set, vonage auth show will output (and check) the authentication settings. 

Tip: Add --show-all if you want to see non-redacted values.

vonage auth show

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

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

✅ Checking API Key Secret

Some commands will only function against a Vonage application. You can set the application settings using --app-id and --private-key

Note: You will also need to provide the --api-key and --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

Now, you can use the CLI without needing to pass in credentials for every call. 

Usage

While I won’t review all the commands (they are numerous, and we are constantly adding more), you can use the --help flag anywhere to see all the available commands and how to use them. I will highlight two valuable groups.

JWT Commands

There are two JWT commands: vonage jwt create, and vonage jwt validate. (We use the create command in our cURL code snippets). Validate can be helpful if you encounter authentication issues when making API calls. Now, since we configured the CLI in the previous section, running vonage jwt create will use those credentials:

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

You can also, in an ACL, subject and set a custom expiration time:

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

Tip: On MacOS, the pbcopy command will output a command into your clipboard. This is done by adding a pipe after the command vonage jwt create | pbcopy.

The validate command can check that the token is correctly signed to your application, but it can also check the other claims as well:

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

Application Commands

I want to highlight vonage apps since they are the most used and have significantly changed this version. The major change is with creating applications. The previous version allowed you to create the application and set all the capability settings simultaneously. V3 breaks this out into two separate commands. As we have expanded our product lines, the number of flags needed to configure all these capabilities has grown. Furthermore, if you wanted to make a small change to one capability, you would have to pass in the entire configuration or risk changing unrelated capabilities. Let’s walk through how to set up an application that has messages and verify capabilities configured.

Start by creating a new application:

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

Note: For those familiar with V1, the CLI will no longer generate a name for your application; you must specify one.

Next, we will configure messages using vonage apps capabilities update <application id> 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

And now we add verify by just changing messages to 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

Tip: If you want to unset a value (for example, messages status URL), you can pass in remove as the value: --messages-status-url=’__remove__’.

Final comments

Using a CLI in 2025 might feel outmoded, but you might not want to share the dashboard credentials with everyone in your organization. Our Subaccounts API allows you to create isolated accounts with their API Keys and Secrets. CLI programs also assist with automation processes. Create a test Vonage application for your staging environment to give you confidence that your code will function with vonage services. (Keep an eye out for vonage verify soon to add MFA easily).

We are not done adding new commands and features to the CLI. Use --help anywhere to see all the available commands and how to use them. You can also check out our "Getting Started with Vonage CLI" page or the GitHub repository