Getting Started with the Vonage CLI

The Vonage CLI has many commands that allow you to programmatically set up and configure applications on your server, as well as quickly export the configuration into JSON or YAML to consume in your programs.

Installation

The Vonage CLI is written with NodeJS and utilizes the @vonage/server-sdk package, which you can find on GitHub. The CLI will always work with the lowest Long Term Supported (LTS) version of NodeJS (currently 18.20).

Note: Odd-numbered version numbers of NodeJS are considered experimental and will only have limited support.

Installing with npm

To install the Vonage CLI using npm, run the following command:

npm install -g @vonage/cli

Installing with yarn

To install the Vonage CLI using yarn:

yarn global add @vonage/cli

Initial Configuration

The Vonage CLI uses a flexible configuration system to manage your API credentials. It supports local or global configuration files and command-line flags for overriding these values, allowing you to tailor your setup based on your project needs or personal preferences.

The CLI will load the configuration in the following order:

  1. Command line flags:
  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.

Note: Only the CLI will read these values from .vonagerc. The Vonage SDKs require separate initialization with their own credentials.

Note: The contents of the private key will be stored inside the configuration file. This is designed to help ensure the key is not overwritten when new keys are generated

Set Authentication

While you can use the CLI without configuring it, you will be required to pass in the flags when running a command.

Using the vonage auth set command is recommended to save you from typing them every time you run a command.

Flags

This command uses the following global authentication flags:

  • --api-key: The API key found in the "API settings" section of your dashboard.
  • --api-secret: The API secret found in the "API Settings" section of your dashboard.
  • --app-id: The ID of the application to use. This is found in the "Applications" section of the dashboard or outputted with vonage apps.
  • --private-key: The path or contents of the private key. The private key can only be accessed when the application is created or when you regenerate the keys in the dashboard.

When submitted, it will check the credentials are correct before committing.

Note: running vonage auth set will not remove current values, and will only update any config files with user confirmation. Therefore, you can set just the API Key/Secret or App ID/Private Key individually. However, you will not be able to set the App ID and Private key without having the API key and secret set.

Examples

To configure your Vonage API credentials:

vonage auth set `
--api-key='your-api-key' `
--api-secret='your-api-secret' `
--app-id='your-application-id' `
--private-key=C:\path\to\private.key

API Key: your-api-key
API Secret: your-**************
App ID: your-application-id
Private Key: Is Set

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

Using the CLI

Viewing Available Commands

Commands are grouped by product or action. To view a list of available commands, just run vonage without any arguments:

vonage 

vonage <command>

Commands:
  vonage apps [command]           Manage applications
  vonage auth [command]           Manage authentication information
  vonage balance                  Check your account balance
  vonage conversations [command]  Manage conversations
  vonage jwt <command>            Manage JWT tokens
  vonage members [command]        Manage applications
  vonage numbers [command]        Manage numbers
  vonage tunnel <which>           Open a tunnel in order to test webhooks
  vonage users [command]          Manage users

Options:
      --version   Show version number                                                                                                                                                  [boolean]
  -v, --verbose   Print more information                                                                                                                                               [boolean]
  -d, --debug     Print debug information                                                                                                                                              [boolean]
      --no-color  Toggle color output off                                                                                                                                              [boolean]
  -h, --help      Show help                                                                                                                                                            [boolean]

You can add the --help flag anywhere to see all of the available commands and how to use them.

Global Flags

The Vonage CLI provides a set of global flags that are available for all commands:

  • --version: Show the version of the CLI that's currently installed.
  • --no-color: Toggle color output off.
  • --help: Show help.
  • --yaml: Output in YAML format.
  • --json: Output in JSON format.

Only some commands are compatible with the YAML and JSON flags. You can use the --help flag with any command to see if they can be used.

Debugging

The --verbose and --debug flags can also be used to show additional information on how the CLI is running. See the Debugging guide for further details, including exit codes.

Need Help?

If you encounter any issues or need help, please join our community Slack channel.