Nexmo CLI

❗ Th CLI has moved! It is now the Vonage CLI. We will support this repository for 12 months, ending October 2022, with any needed bug or security fixes for the last release. New features will be released under the Vonage CLI`, so to take advantage of those please make sure to switch as soon as possible so you don't miss out!

Installation | Usage | Contributing | License

Installation

The Nexmo CLI requires Node.js 4 or above. If you don't have Node.js installed on your system, go to https://nodejs.org/en/download/ and download the appropriate installer for your system.

With Node.js installed, you can then install the nexmo-cli package from the npm registry.

npm install nexmo-cli -g   # Using npm
yarn global add nexmo-cli  # Using yarn

If you see an EACCES error when you try to install a package globally, follow the steps outlined at How to Prevent Permissions Errors.

After installation, set up the CLI with your Nexmo API key and secret:

> nexmo setup <api_key> <api_secret>
Credentials written to /Users/yourname/.nexmorc

This will save your credentials to ~/.nexmorc. If you want to use different credentials per project, you can pass the --local flag as follows:

> nexmo setup <api_key> <api_secret> --local

This will save the config to your local folder instead.

Usage

Flags | Account | Pricing | Numbers | SMS | Applications | Linking | Insight | JWT

Flags

Use --quiet to silence all but errors and warnings, and use --verbose to get more detailed output.

Account

Account login

> nexmo setup <api_key> <api_secret>
Credentials written to /home/username/.nexmorc

Alias: nexmo s.

Account info

> nexmo account
API Key:    <api_key>
API Secret: <api_secret>

> nexmo account:key
<api_key>

> nexmo account:secret
<api_secret>

Alias: nexmo a.

Account balance

> nexmo balance
18.96 EUR

> nexmo balance -v
18.9589 EUR

Alias: nexmo b

Pricing

Price to send an SMS to a number

> nexmo price:sms 44555555555
0.03140000 EUR

Alias: nexmo ps

Price to make a call to a number

> nexmo price:voice 44555555555
0.02400000 EUR

Alias: nexmo pv

Price for outbound SMS per country

> nexmo price:country GB
0.03140000 EUR

> nexmo price:country LU -v

network           | mtPrice
------------------------------
POST Luxembourg   | 0.01280000
Orange Luxembourg | 0.01280000
Join Experience   | 0.01280000
Tango             | 0.01280000

Alias: nexmo pc

Numbers

List all numbers on your account

• Optional flags:

  • --size The number of results to return
  • --page The page of results to return
  • --pattern <pattern> to be matched in number (use * to match end or start of number)

> nexmo numbers:list
31555555555
44655555555
44555555555

> nexmo numbers:list --verbose
Item 1-3 of 3

msisdn      | country | type       | features  | voiceCallbackType | voiceCallbackValue | moHttpUrl | voiceStatusCallbackUrl
----------------------------------------------------------------------------------------------------------------------------
31555555555 | NL      | mobile-lvn | VOICE,SMS | app               | b6d9f957           | undefined | https://example.com
44655555555 | GB      | mobile-lvn | VOICE,SMS | app               | b6d9f957           | undefined | https://example.com
44555555555 | GB      | mobile-lvn | SMS       | app               | b6d9f957           | undefined | https://example.com

Alias: nexmo nl, nexmo numbers and nexmo number:list.

Search for new numbers

Parameters:

• country_code - an ISO 3166-2 country code for the country you are trying to find a number for.

• Optional flags:

  • --pattern <pattern> to be matched in number (use * to match end or start of number)
  • --voice to search for voice-enabled numbers
  • --sms search for SMS enabled numbers
  • --size the number of results to return
  • --page the page of results to return

> nexmo number:search US
12057200555
12069396555
12069396555
12155961555

> nexmo number:search NL --sms --pattern *007 --verbose
msisdn      | country | cost | type       | features
-----------------------------------------------------
31655551007 | NL      | 3.00 | mobile-lvn | VOICE,SMS
31655552007 | NL      | 3.00 | mobile-lvn | VOICE,SMS
31655553007 | NL      | 3.00 | mobile-lvn | VOICE,SMS

Alias: nexmo ns and nexmo numbers:search.

Buying a number

Parameters:

• number - The number to buy
• or country_code and pattern - The country and search pattern to find a number for and directly buy.

> nexmo number:buy 12069396555
Buying 12069396555\. This operation will charge your account.

Please type "confirm" to continue: confirm

Number purchased

> nexmo number:buy US *555
Buying 12069396555\. This operation will charge your account.

Please type "confirm" to continue: confirm

Number purchased: 12069396555

> nexmo number:buy 12069396555 --confirm
Number purchased: 12069396555

Alias: nexmo nb and nexmo numbers:buy.

Cancelling a number

> nexmo number:cancel 12069396555
This operation can not be reversed.

Please type "confirm" to continue: confirm

Number cancelled: 12069396555

> nexmo number:cancel 12069396555 --confirm
Number cancelled: 12069396555

Alias: nexmo nc and nexmo numbers:cancel.

Update a number

For shortcuts of these options see Linking.

> nexmo number:update 445555555555 --voice_callback_type app --voice_callback_value asdasdas-asdd-2344-2344-asdasdasd345
Number updated

Alias: nexmo nu and nexmo numbers:update.

SMS

Send an SMS

Send a message through Nexmo to any number. Either provide a from number, name, or leave it blank to sends as "Nexmo CLI".

> nexmo sms <destination_number> Hello world! --confirm
Message sent to:   <destination_number>
Remaining balance: 26.80110000 EUR
Message price:     0.03330000 EUR

> nexmo sms  <destination_number> Hello world! --from "Acme Inc" --confirm
Message sent to:   <destination_number>
Remaining balance: 26.80110000 EUR
Message price:     0.03330000 EUR

Note: Some carriers (e.g. US and Canadian) do not allow alphanumeric senders. In these cases, you must use one of your Nexmo virtual numbers in the from parameter. For example:

nexmo sms <to_number> Hello world! --from <from_number> --confirm

Applications

List your Applications

• Optional flags:

  • --size The number of results to return
  • --page The page of results to return

> nexmo app:list
asdasdas-asdd-2344-2344-asdasdasd123 | Test Application 1
asdasdas-asdd-2344-2344-asdasdasd234 | Test Application 1
asdasdas-asdd-2344-2344-asdasdasd345 | Test Application 2

> nexmo app:list --verbose
Item 1-3 of 3

id                                   | name
---------------------------------------------------------
asdasdas-asdd-2344-2344-asdasdasd123 | Test Application 1
asdasdas-asdd-2344-2344-asdasdasd234 | Test Application 1
asdasdas-asdd-2344-2344-asdasdasd345 | Test Application 2

Alias: nexmo al and nexmo apps.

Create a new Application

Parameters:

• name - the custom name of your application.

• answer_url - the URL where your webhook delivers the Nexmo Call Control Object that governs this call.

• event_url - the URL the platform sends event information asynchronously to when the call_status changes

• Optional flags:

  • --keyfile <keyfile> The file to save your private key to
  • --type <type> The product you want to access with this application. (Default: voice)
  • --answer_method <answer_method> The http method for the answer_url. (Default: GET)
  • --event_method <event_method> The http method for the event_url. (Default: GET)

> nexmo app:create "Test Application 1" http://example.com http://example.com  --keyfile private.key
Application created: asdasdas-asdd-2344-2344-asdasdasd345
Private Key saved to: private.key

> nexmo app:create "Test Application 1" http://example.com http://example.com -v
[id]
asdasdas-asdd-2344-2344-asdasdasd345

[name]
Test Application 1

[voice.webhooks.0.endpoint_type]
event_url

[voice.webhooks.0.endpoint]
http://example.com

[voice.webhooks.0.http_method]
POST

[voice.webhooks.1.endpoint_type]
answer_url

[voice.webhooks.1.endpoint]
http://example.com

[voice.webhooks.1.http_method]
GET

[keys.public_key]
...

[keys.private_key]
...

[_links.self.href]
/applications/asdasdas-asdd-2344-2344-asdasdasd345

Alias: nexmo ac.

Show details for an Application

> nexmo app:show asdasdas-asdd-2344-2344-asdasdasd345
[id]
asdasdas-asdd-2344-2344-asdasdasd345

[name]
Test Application 1

[voice.webhooks.0.endpoint_type]
event_url

[voice.webhooks.0.endpoint]
http://example.com

[voice.webhooks.0.http_method]
POST

[voice.webhooks.1.endpoint_type]
answer_url

[voice.webhooks.1.endpoint]
http://example.com

[voice.webhooks.1.http_method]
GET

[keys.public_key]
...

[_links.self.href]
/applications/asdasdas-asdd-2344-2344-asdasdasd345


Private Key saved to: private.key

Alias: nexmo as and nexmo app.

Update an Application

Parameters:

• app_id - the UUID of your application.

• name - the custom name of your application.

• answer_url - the URL where your webhook delivers the Nexmo Call Control Object that governs this call.

• event_url - the URL the platform sends event information asynchronously to when the call_status changes

• Optional flags:

  • --type <type> The product you want to access with this application. (Default: voice)
  • --answer_method <answer_method> The http method for the answer_url. (Default: GET)
  • --event_method <event_method> The http method for the event_url. (Default: GET)

> nexmo app:update asdasdas-asdd-2344-2344-asdasdasd345 "Test Application 1" http://example.com http://example.com
Application updated: asdasdas-asdd-2344-2344-asdasdasd345

> nexmo app:update asdasdas-asdd-2344-2344-asdasdasd345 "Test Application 1" http://example.com http://example.com -v
[id]
asdasdas-asdd-2344-2344-asdasdasd345

[name]
Test Application 1

[voice.webhooks.0.endpoint_type]
event_url

[voice.webhooks.0.endpoint]
http://example.com

[voice.webhooks.0.http_method]
POST

[voice.webhooks.1.endpoint_type]
answer_url

[voice.webhooks.1.endpoint]
http://example.com

[voice.webhooks.1.http_method]
GET

[keys.public_key]
...

[keys.private_key]
...

[_links.self.href]
/applications/asdasdas-asdd-2344-2344-asdasdasd345

Alias: nexmo au.

Delete an application

Parameters:

• app_id - The UUID of your application.

> nexmo app:delete asdasdas-asdd-2344-2344-asdasdasd345
This operation can not be reversed.

Please type "confirm" to continue: confirm

Application deleted

> nexmo app:delete asdasdas-asdd-2344-2344-asdasdasd345 --confirm
Application deleted

Alias: nexmo ad.

Show numbers for an application

Parameters:

• app_id - The UUID of your application.

• Optional flags:

  • --size The amount of results to return
  • --page The page of results to return

> nexmo app:numbers asdasdas-asdd-2344-2344-asdasdasd345
31555555555
44655555555
44555555555

> nexmo app:numbers asdasdas-asdd-2344-2344-asdasdasd345 --verbose
Item 1-3 of 3

msisdn      | country | type       | features  | voiceCallbackType | voiceCallbackValue | moHttpUrl | voiceStatusCallbackUrl
----------------------------------------------------------------------------------------------------------------------------
31555555555 | NL      | mobile-lvn | VOICE,SMS | app               | b6d9f957           | undefined | https://example.com
44655555555 | GB      | mobile-lvn | VOICE,SMS | app               | b6d9f957           | undefined | https://example.com
44555555555 | GB      | mobile-lvn | SMS       | app               | b6d9f957           | undefined | https://example.com

Alias: nexmo an and nexmo apps:numbers.

Linking

Link a number to an app

> nexmo link:app 12057200555 asdasdas-asdd-2344-2344-asdasdasd345
Number updated

> nexmo unlink:app 12057200555
Number updated

Alias: nexmo la

Link a number to another phone number

> nexmo link:tel 12057200555 4455555555
Number updated

> nexmo unlink:tel 12057200555
Number updated

Alias: nexmo lt

Link a number to an SMS callback URL

> nexmo link:sms 12057200555 http://example.com/callback
Number updated

> nexmo unlink:sms 12057200555
Number updated

Alias: nexmo lsms

Link a number to a Voice XML callback URL

> nexmo link:vxml 12057200555 http://example.com/callback
Number updated

> nexmo unlink:vxml 12057200555
Number updated

Alias: nexmo lv

Link a number to SIP URI

> nexmo link:sip 12057200555 sip:[email protected]
Number updated

> nexmo unlink:sip 12057200555
Number updated

Alias: nexmo lsip

Insight

Insight Basic

This is the free Number Insight API:

> nexmo insight:basic 447555555555
447555555555 | GB

Alias: nexmo insight and nexmo ib

Insight Standard

This API will charge your account but provide additional details:

> nexmo insight:standard 447555555555 --confirm
447555555555 | GB | Telefonica UK Limited

Verbose mode will return additional information.

Alias: nexmo is

Insight Advanced

This API will charge your account but provide additional details:

> nexmo insight:advanced 447555555555 --confirm
447555555555 | GB | Telefonica UK Limited

Verbose mode will return additional information.

Alias: nexmo ia

JWT

Generate

jwt:generate [options] <private_key> [claim=value...]

Generate a JWT for your voice application.

> nexmo jwt:generate path/to/private.key application_id=asdasdas-asdd-2344-2344-asdasdasd345

Generate a JWT for the Client SDK

> nexmo jwt:generate path/to/private.key subject=username application_id=asdasdas-asdd-2344-2344-asdasdasd345

Contributing

This project is written in ES2015 and compiled using Babel. The source can be found in the /src folder, and the build is compiled to the /lib folder.

To add changes, fork and clone the project.

npm install        # to install all dependencies
npm run build      # to explicitly build the source
npm install -g ./  # to implicitly build the source, and then install the `nexmo` binary into your PATH
npm test           # to run all tests
npm run watch:test # to watch for changes and run tests

You can run the nexmo command with the --debug / -d flag to get extra debug info from the underlying Node.js library.

License

This library is released under the MIT License