Managing applications with the Vonage CLI

The Vonage CLI allows you to create and manage your Vonage applications. To obtain help type vonage apps --help once the CLI has been installed. Like most of the vonage commands, you are able to use the --json and --yaml flags to have the output be in those formats.

Listing your applications

By default, when you run vonage apps it will run the same sub-command as vonage apps list. There are a number of flags you can pass to refine your search:

  • app-name - Allows filtering by application name
  • capability - Filter application by capability. Use a comma , to mean the app has either or and a plus + to mean the application must have both
vonage apps

✅ Loading applications... Done

App ID                                Name               Capabilities
------------------------------------  -----------------  ------------------------------------------------------
00000000-0000-0000-0000-000000000000  Application        None
00000000-0000-0000-0000-000000000000  voice Application  Messages, Voice
00000000-0000-0000-0000-000000000000  All enabled        Messages, Network APIs, RTC, VBC, Verify, Video, Voice

Show application details

The show sub command, allows you to get the details of a specific application. The format of the command is vonage apps show <id> where <id> is the UUID of the application.

Note: This will not display the public key. If you need to view the public key, you can use the --json or --yaml flags which will not redact any information

vonage apps show 00000000-0000-0000-0000-000000000000

✅ Fetching application

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

Capabilities:
  VOICE:
    Uses Signed callbacks: On
    Conversation TTL: 41 hours
    Leg Persistence Time: 6 days
    Event URL: [GET] https://example.com/voice/event
    Answer URL: [GET] https://example.com/voice/answer
    Fallback URL: [GET] https://example.com/voice/fallback
  
  MESSAGES:
    Authenticate Inbound Media: On
    Webhook Version: v1
    Status URL: [POST] https://example.com/meetings/status
    Inbound URL: [POST] https://example.com/meetings/inbound
  
  VERIFY:
    Webhook Version: v2
    Status URL: [POST] https://example.com/verify2/status
  
  RTC:
    Event URL: [POST] https://example.com/rtc/event
    Uses Signed callbacks: On
  
  VIDEO:
    Archive Status URL: [POST] https://example.com/video/archive-status
    Archive Status Signature Secret: archive status
    Broadcast Status URL: [POST] https://example.com/video/broadcast-status
    Broadcast Status Signature Secret: broadcast status
    Caption Status URL: [POST] https://example.com/video/caption-status
    Caption Status Signature Secret: caption-status
    Connection Created URL: [POST] https://example.com/video/connected-created
    Connection Created Signature Secret: connection created
    Connection Destroyed URL: [POST] https://example.com/video/connection-destroyed
    Connection Destroyed Signature Secret: connection destroyed
    Render Status URL: [POST] https://example.com/video/render-status
    Render Status Signature Secret: render status
    SIP Call Created URL: [POST] https://example.com/video/sip1
    SIP Call Created Signature Secret: Off
    SIP Call Destroyed URL: [POST] https://example.com/video/sip3
    SIP Call Destroyed Signature Secret: Off
    SIP Call Mute Forced URL: [POST] https://example.com/video/sip4
    SIP Call Mute Forced Signature Secret: Off
    SIP Call Updated URL: [POST] https://example.com/video/sip2
    SIP Call Updated Signature Secret: Off
    Stream Created URL: [POST] https://example.com/video/stream-created
    Stream Created Signature Secret: stream created
    Stream Destroyed URL: [POST] https://example.com/video/stream-destroyed
    Stream Destroyed Signature Secret: stream destroyed
  
    RECORDINGS STORAGE:
      Cloud Storage: On
      Storage Type: AmazonS3
      Credential: manchuck_aws_bucket
      End to End Encryption: On
      Server Side Encryption: On
  
  NETWORK APIS:
    Redirect URL: [GET] https://example.com/gnp/redirect
  
  NB: VBC capabilities is not supported through the command line.

Creating an application

The create subcommand allows you to create an application. Previous versions of the CLI allowed you to also set the application capabilities, however, that has been removed with version 3 of the CLI - the reasons why are explained below. You are now required to pass in an application name as the CLI will no longer generate one for you. vonage apps create <name> now has the following parameters/flags:

  • public-key-file - A link to the public key file you wish to use with the application.
  • private-key-file - The full path on where you want to save the generated private key (cannot be used with public-key-file).
  • improve-ai - Allow vonage to use this application data to train AI models.

Note: If you do not supply your own key, Vonage will create one for you. However, if you do not save the key when the application is created, you will not be able to access it again. You will have to regenerate the key if you lose it.

vonage apps create 'Your application'

✅ Creating Application
Saving private key ... Done!
Application created

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

Capabilities:
  None Enabled

Updating an application

After you create an application, you can update the name, Improve AI, or set a new public key. vonage apps update <id> have the same flags as vonage apps create except for private-key-file.

vonage apps update 00000000-0000-0000-0000-000000000000 `
  --name="New Application Name"
  
✅ Fetching Application
✅ Updating Application

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

Deleting an application

You can delete an application with the command vonage apps delete <id>, where id is the UUID of the application:

vonage apps delete 00000000-0000-0000-0000-000000000000

✅ Fetching application
Delete application New Name (7d7133ab-de4e-4b7a-8e1e-376670077c71)? [y/n] 
✅ Deleting application

Managing capabilities for an application

In previous versions of the CLI, it required you to pass in all values when you wanted to modify a capability for an application. This meant that you had to remember what the current values were, and if you did not include a flag or entered an incorrect value, the capability would not function as expected. Version 3 of the CLI solves this by having a new sub command to manage application capabilities. The command format is as follows: vonage apps capabilities <action> <id> <which> [flags].

Managing numbers for an application

Version 3 of the CLI allows you to easily manage numbers for an application. There are two main commands: vonage apps numbers list <id>, and, vonage apps numbers <link|unlink> <id> <msisdn>. Using these commands will ensure that numbers are linked properly.

Listing the numbers linked to an application

To list all the numbers linked to an application, simply run vonage apps numbers list <id> where id is the UUID for the application. If you pass in the --fail flag, this command will exit with code 1 if the application does not have either messages or voice capabilities.

Note: This will page through all the numbers you have linked. This might take some time depending on how many numbers are linked

vonage apps numbers list 00000000-0000-0000-0000-000000000000

✅ Fetching Application
Fetching numbers linked to application Your application [==============] 1/1 100%

There is 1 number linked:

Number       Country             Type       Features       
-----------  ------------------  ---------  ---------------
16127779311  🇺🇸 United States    Mobile     MMS, SMS, VOICE

Linking/Unlinking a number to an application

Numbers can be linked using vonage apps <link|unlink> <id> <msisdn>.

vonage apps numbers link 00000000-0000-0000-0000-000000000000 16127779311

✅ Fetching Application
Fetching Owned numbers [===============================================] 1/1 100%

Number linked

Number: 16127779311
Country: 🇺🇸 United States
Type: Toll-free
Features: MMS, SMS, VOICE
Monthly Cost: Not Set
Setup Cost: Not Set
Linked Application ID: 00000000-0000-0000-0000-000000000000
Voice Callback: app
Voice Callback Value: 00000000-0000-0000-0000-000000000000
Voice Status Callback: Not Set

Reference