Nexmo CLI

You use the Nexmo Command Line Interface (CLI) to manage your Nexmo account and use Nexmo products from the command line.

  • Install - use NPM to install the Nexmo CLI
  • Use - manage your Nexmo account and use some Nexmo products
  • Contribute - add more features to the Nexmo Cli
  • License - this product is distributed under the MIT license

npm version Build Status

Install

The Nexmo CLI requires NodeJS 4 or above. If you don't have Node installed on your system, download the installer from https://nodejs.org/en/download/.

To setup the Nexmo CLI:

  1. Use NPM to install the Nexmo CLI:
    sudo npm install nexmo-cli -g
  2. Setup the CLI with your Nexmo API key and secret:
    > nexmo setup <api_key> <api_secret>
    Credentials written to /Users/yourname/.nexmorc

    To use different credentials for a project, add the --local flag

  3. Your credentials are saved in .nexmorc.
    Global credentials are saved in your home directory. Local credentials in the directory where you ran nexmo setup.

Alias: nexmo s.

Use

You use the Nexmo CLI to configure or retrieve information related to your Nexmo account.

Function Command Description
Account nexmo account Retrieve your Nexmo api_key and api_secret.
  nexmo balance Retrieve the current balance in your Nexmo account.
  nexmo price:sms Retrieve the cost of sending an SMS to a phone number.
  nexmo price:voice Retrieve the cost per minute of a voice call to a phone number.
  nexmo price:country Retrieve the cost of sending an SMS to a country.
Numbers nexmo numbers:list List the virtual numbers you are currently renting from Nexmo.
  nexmo number:search Retrieve the inbound numbers that are available in a given country.
  nexmo number:buy Rent an inbound virtual number.
  nexmo number:cancel Cancel your rental of an inbound virtual number.
  nexmo number:update Change the webhook endpoints associated with a virtual number.
SMS nexmo sms Send an SMS anywhere in the world.
Applications nexmo app:list List your Nexmo Applications.
  nexmo app:create Create a new Application.
  nexmo app:show Retrieve details about a specific Application.
  nexmo app:update Modify an existing Application.
  nexmo app:delete Delete an existing Application.
Authentication nexmo jwt:generate Generate a JSON Web Token (JWT) to authenticate calls to Nexmo API for your Application.
Linking nexmo link:app Link one of your virtual numbers to an Application.
  nexmo link:tel Forward inbound calls to your virtual number to a phone number.
  nexmo link:sms Forward incoming messages to a webhook endpoint.
  nexmo link:vxml Retrieve VXML from your webhook endpoint to manage incoming calls to a virtual number.
  nexmo link:sip Forward incoming phone calls to a SIP URI.
Number Insight nexmo insight:basic Retrieve local and international representations of a phone number.
  nexmo insight:standard Identify the phone number type and, for mobile phone numbers, the network it is registered with.

Global flags:

  • --quiet - only see errors and warnings
  • --verbose - more detailed output
  • --debug - retrieve debug information while you are running the Nexmo CLI

nexmo account

Retrieve the api_key and api_secret for your Nexmo account:

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

The syntax is:

  • nexmo account

There are no parameters.

nexmo balance

Retrieve the current balance in your Nexmo account:

> nexmo balance
18.96 EUR

> nexmo balance -v
3.07484582 EUR

The syntax is: nexmo balance

Possible parameters and flags are:

Name Description Required
-v Return the balance to eight decimal points No

Alias: nexmo b

nexmo price:sms

Retrieve the cost of sending an SMS to a phone number.

> nexmo price:sms 441632960960
0.03140000 EUR
 
 
Alias: nexmo ps

The syntax is: nexmo price:sms <phone_number>

Possible parameters and flags are:

Name Description Required
phone_number The phone number to call in E.164 format. For example: 441632960960. Yes

nexmo price:voice

Retrieve the cost per minute of a voice call to a phone number.

> nexmo price:voice 44555555555
0.02400000 EUR
 
Alias: nexmo pv

The syntax is: nexmo price:voice <phone_number>

Possible parameters and flags are:

Name Description Required
phone_number The phone number to call in E.164 format. For example: 441632960960. Yes

nexmo price:country

Retrieve the cost of sending an SMS to a 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

The syntax is: nexmo price:country <country_code>

Possible parameters and flags are:

Name Description Required
country_code The country code in ISO_3166-1_alpha-2 format that you want to call. For example: GB. Yes

nexmo numbers:list

List the virtual numbers you are currently renting from Nexmo.

> nexmo numbers:list
441632960960
441632960961
441632960962
 
> nexmo numbers:list --verbose
Item 1-3 of 3
 
msisdn      | country | type       | features  | voiceCallbackType | voiceCallbackValue | moHttpUrl | voiceStatusCallbackUrl
----------------------------------------------------------------------------------------------------------------------------
441632960960 | GB      | mobile-lvn | VOICE,SMS | app               | b6d9f957           | undefined | https://example.com
441632960961 | GB      | mobile-lvn | VOICE,SMS | app               | b6d9f957           | undefined | https://example.com
441632960962 | GB      | mobile-lvn | SMS       | app               | b6d9f957           | undefined | https://example.com

The syntax is: nexmo numbers:list

Possible parameters and flags are:

Name Description Required
--size The number of items returned in each page of the response. The default value is 10, the maximum size is 100. No
--page The index for the page in the response. For example, set to 3 to retrieve items 31 - 40 where size is the default value. No

Alias: nexmo nl, nexmo numbers.

Retrieve the inbound numbers that are available in a certain country:

> 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

The syntax is: nexmo number:search <country_code>

Possible parameters and flags are:

Name Description Required
country_code The two character country code in ISO 3166-1 alpha-2 format. For example, ES for Spain. Yes
--pattern <pattern> A number pattern to search for. For example, 888 searches for any available virtual number where the first three digits are 888. Use * to match the end or the start of a phone number. No
--voice Search for Voice enabled phone numbers. This is the default value. No
--sms Search for SMS enabled phone numbers. No
--size The number of items returned in each page of the response. The default value is 10, the maximum size is 100. No
--page The index for the page in the response. For example, set to 3 to retrieve items 31 - 40 where size is the default value. No

Note: to search for Voice and SMS enabled phone numbers, add --voice --sms to your command.

Alias: nexmo ns and nexmo numbers:search.

nexmo number:buy

Rent an inbound virtual number:

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

Please type "confirm" to continue: confirm

Number purchased

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

Please type "confirm" to continue: confirm

Number purchased: 441632960961

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

The syntax is: nexmo number:buy <virtual_number> | <country_code> | <pattern>

Possible parameters and flags are:

Name Description Required
virtual_number The virtual number to rent. No
country_code To rent a virtual number without choosing, set the two character country code in ISO 3166-1 alpha-2 format. For example, ES for Spain. Yes
pattern <pattern> To rent a virtual number without choosing, set a number pattern to search for. For example, 888 searches for any available virtual number where the first three digits are 888. Use * to match the end or the start of a phone number. No

Alias: nexmo nb and nexmo numbers:buy.

nexmo number:cancel

Cancel your rental of an inbound virtual number:

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

Please type "confirm" to continue: confirm

Number cancelled: 441632960960

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

The syntax is: nexmo number:cancel <virtual_number>

Possible parameters and flags are:

Name Description Required
virtual_number The virtual number you are currently renting from Nexmo. Yes
--confirm Cancel the rental directly, there is no confirmation step. No

Alias: nexmo nc and nexmo numbers:cancel.

nexmo number:update

Change the webhook endpoints associated with a virtual number.

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

The syntax is: nexmo number:update <virtual_number> <application_id>

Possible parameters and flags are:

Name Description Required
virtual_number The virtual number you are renting from Nexmo. Yes
--voice_callback_type The voice webhook type. Possible values are:
  • sip - a SIP endpoint
  • tel - a telephone number
  • vxml - a VoiceXML endpoint
  • app - an Application
No
--voice_callback_value Either: . No

Alias: nexmo nu and nexmo numbers:update.

nexmo sms

Send an SMS anywhere in the world.

> 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

The syntax is: nexmo sms <destination_number> <message>

Possible parameters and flags are:

Name Description Required
destination_number A single phone number in international format, that is E.164. For example, to=447525856424. You can set one recipient only for each request. Yes
message The SMS body. Messages are in UTF-8 with URL encoding. You send "Déjà vu" as a text (type=text) message as long as you encode it as D%C3%A9j%C3%A0+vu. You can see the full UTF-8 character set here: http://www.fileformat.info/info/charset/UTF-8/list.htm. To test if your message can be URL encoded, use: http://www.url-encode-decode.com/. If you cannot find the character you want to send in these two references, you should use unicode. For more information, see Encoding. Yes
--from An alphanumeric string giving your sender address. For example, "Acme Inc". The default value is "Nexmo CLI". Some carriers do not allow alphanumeric senders. This sender address must be a Nexmo virtual number. See Custom senderID. No
--confirm Send the SMS directly, there is no confirmation step. No

nexmo app:list

List your Nexmo Applications:

> 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

The syntax is: nexmo app_list

Possible parameters and flags are:

Name Description Required
--size The number of items returned in each page of the response. The default value is 10, the maximum size is 100. No
--page The index for the page in the response. For example, set to 3 to retrieve items 31 - 40 where size is the default value. No

Alias: nexmo al and nexmo apps.

nexmo app:create

Create a new application:

> 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

The syntax is: nexmo app:create <name> <answer_url> <event_url>

Parameters:

Possible parameters and flags are:

Name Description Required
name The name of your application. Yes
answer_url The URL where your webhook delivers the Nexmo Call Control Object that governs this call. Yes
event_url The url Nexmo sends event information asynchronously to when the call_status changes. Yes
--answer_method <method> The HTTP method used to make the request to answer_url. The default value is GET. No
--event_method <method> The HTTP method used to send event information to event_url. The default value is POST. No
--keyfile <file> The file to save your private key to No
--type The Nexmo product or products that you access with this application. Possible values are:
  • voice - Voice API
  • rtc - Conversation AP
The default value is voice.
No

Alias: nexmo ac.

nexmo app:show

Retrieve details about a specific 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

The syntax is: nexmo app:show <application_id>

Parameters:

Possible parameters and flags are:

Name Description Required
application_id The UUID of the Application you want information for. Yes

Alias: nexmo as and nexmo app.

nexmo app:update

Modify an existing Application.

> 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

The syntax is: nexmo app:update <application_id> <name> <answer_url> <event_url>

Possible parameters and flags are:

Name Description Required
application_id The UUID of the Application to update. Yes
name The name of your application. Yes
answer_url The URL where your webhook delivers the Nexmo Call Control Object that governs this call. Yes
event_url The url Nexmo sends event information asynchronously to when the call_status changes. Yes
--answer_method <method> The HTTP method used to make the request to answer_url. The default value is GET. No
--event_method <method> The HTTP method used to send event information to event_url. The default value is POST. No

Alias: nexmo au.

nexmo app:delete

Delete an existing Application.

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

Please type "confirm" to continue: confirm

Application deleted

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

The syntax is: nexmo app:delete <application_id>

Possible parameters and flags are:

Name Description Required
application_id The UUID of the Application to update. Yes
--confirm Delete the Application directly, there is no confirmation step. No

Alias: nexmo ad.

nexmo jwt:generate

Generate a JSON Web Token (JWT) to authenticate calls to Nexmo API for your Application.

> nexmo jwt:generate path/to/private.key subject=username iat=1475861732
[...JWT String...]
> nexmo jwt:generate path/to/private.key subject=username iat=1475861732 --app_id asdasdas-asdd-2344-2344-asdasdasd345
> JWT: [...JWT String...]

The syntax is: jwt:generate <private_key_path> <subject> <iat>

Possible parameters and flags are:

Name Description Required
private_key_path The path to the file where you saved the private key assocated with this Application. Yes
iat The time in UTC+0 at which the JWT was issued Yes
subject The name for the User you are trying to authenticate. No
application_id The UUID of the Application you are generating this JWT for. No

This call optionally supports extra claims to be passed in.

Link a virtual number to an Application.

The syntax is: nexmo link:app <virtual_number> <application_id>

Possible parameters and flags are:

Name Description Required
virtual_number The virtual number to link. Yes
application_id The UUID of the Application to link. Yes

Alias: nexmo la

Note: to remove the link, call nexmo unlink:app <virtual_number>.

Inbound calls to virtual_number are forwarded to a phone number.

The syntax is: nexmo link:tel <virtual_number> <phone_number>
Inbound phone calls to virtual_number are forwarded to phone_number.

Possible parameters and flags are:

Name Description Required
virtual_number The virtual number to link. Yes
phone_number The phone number to forward calls to. Yes

Alias: nexmo lt

Note: to remove the link, call nexmo unlink:tel <virtual_number>.

Forward incoming messages to a webhook endpoint.

The syntax is: nexmo link:sms <virtual_number> <webhook_endpoint>

Possible parameters and flags are:

Name Description Required
virtual_number The virtual number to link. Yes
webhook_endpoint Forward SMS to this endpoint. Yes

Alias: nexmo lsms

Note: to remove the link, call nexmo unlink:sms <virtual_number>.

Retrieve VXML from your webhook endpoint to manage incoming calls to a virtual number.

The syntax is: nexmo link:vxml <virtual_number> <webhook_endpoint>

Possible parameters and flags are:

Name Description Required
virtual_number The virtual number to link. Yes
webhook_endpoint Retrive VXML from this endpoint. Yes

Alias: nexmo lv

Note: to remove the link, call nexmo unlink:vxml <virtual_number>.

Forward an incoming phone call to a SIP URI

The syntax is: nexmo link:sip <virtual_number> <sip_identifier>

Possible parameters and flags are:

Name Description Required
virtual_number The virtual number to link. Yes
sip_identifier The SIP URI to forward incoming calls to. Yes

Alias: nexmo lsip

Note: to remove the link, call nexmo unlink:sip <virtual_number>.

nexmo insight:basic

You use Number Insight Basic API to retrieve local and international representations of a phone number in order to pretty-print numbers in a user interface. Number Insight Basic API performs semantic checks on phone numbers.

> nexmo insight:basic 441632960960
441632960960 | GB

The syntax is: nexmo insight:basic <phone_number>

Possible parameters and flags are:

Name Description Required
phone_number The phone number you want to retrieve information about. Yes

Alias: nexmo insight and nexmo ib

nexmo insight:standard

You use Number Insight Standard API to identify the type of phone number and, for mobile phone numbers, the network it is registered with. You also retrieve the information supplied by Number Insight Basic API.

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

The syntax is: nexmo insight:standard <phone_number>

Possible parameters and flags are:

Name Description Required
phone_number The phone number you want to retrieve information about. Yes
--confirm Return the information directly. there is no confirmation step and your account is charged for the request. No

Alias: nexmo is

Contribute

This project is written in ES2015 and compiled using Babel. You find the source code in /src which is compiled into /lib.

To add changes, fork (if needed) and clone the project from https://github.com/Nexmo/nexmo-cli.

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

To retrieve extra debug info from the underlying Node library, run the Nexmo CLI in debug mode: nexmo --debug.

License

This library is released under the MIT License.

Previous   Next