Nexmo CLI (Command Line Interface)
Nexmo CLI
|
:exclamation: 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!</p> | |-----------------------------------------|
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.
<pre><code class="lang-bash">npm install nexmo-cli -g # Using npm yarn global add nexmo-cli # Using yarn</code></pre>
> 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:
<pre><code class="lang-bash">> nexmo setup <apikey> <apisecret> Credentials written to /Users/yourname/.nexmorc</code></pre>
This will save your credentials to ~/.nexmorc. If you want to use different credentials per project, you can pass the --local flag as follows:
<pre><code class="lang-bash">> nexmo setup <apikey> <apisecret> --local</code></pre>
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
<pre><code class="lang-bash">> nexmo setup <apikey> <apisecret> Credentials written to /home/username/.nexmorc</code></pre>
Alias: nexmo s.
Account info
<pre><code class="lang-bash">> nexmo account API Key: <api_key> API Secret: <api_secret>
> nexmo account:key <api_key>
> nexmo account:secret <api_secret></code></pre>
Alias: nexmo a.
Account balance
<pre><code class="lang-bash">> nexmo balance 18.96 EUR
> nexmo balance -v 18.9589 EUR</code></pre>
Alias: nexmo b
Pricing
Price to send an SMS to a number
<pre><code class="lang-bash">> nexmo price:sms 44555555555 0.03140000 EUR</code></pre>
Alias: nexmo ps
Price to make a call to a number
<pre><code class="lang-bash">> nexmo price:voice 44555555555 0.02400000 EUR</code></pre>
Alias: nexmo pv
Price for outbound SMS per country
<pre><code class="lang-bash">> 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</code></pre>
Alias: nexmo pc
Numbers
List all numbers on your account
- Optional flags:
The number of results to return
- --page The page of results to return
- --pattern to be matched in number (use * to match end or start of number)
<pre><code class="lang-bash">> 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</code></pre>
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 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
<pre><code class="lang-bash">> 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</code></pre>
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.
<pre><code class="lang-bash">> 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</code></pre>
Alias:
nexmo nb and nexmo numbers:buy.
Cancelling a number
<pre><code class="lang-bash">> 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</code></pre>
Alias:
nexmo nc and nexmo numbers:cancel.
Update a number
For shortcuts of these options see Linking.
<pre><code class="lang-bash">> nexmo number:update 445555555555 --voicecallbacktype app --voicecallbackvalue asdasdas-asdd-2344-2344-asdasdasd345 Number updated</code></pre>
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".
<pre><code class="lang-bash">> 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</code></pre>
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:
<pre><code class="lang-bash">nexmo sms <tonumber> Hello world! --from <fromnumber> --confirm</code></pre>
Applications
List your Applications
- Optional flags:
- --size The number of results to return
- --page The page of results to return
<pre><code class="lang-bash">> 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</code></pre>
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.
eventurl - the URL the platform sends event information asynchronously to when the callstatus changes
The file to save your private key to
- --type The product you want to access with this application. (Default: voice)
- --answermethod The http method for the answer_url. (Default: GET)
- --eventmethod The http method for the event_url. (Default: GET)
<pre><code class="lang-">> 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</code></pre>
Alias:
nexmo ac.
Show details for an Application
<pre><code class="lang-bash">> 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</code></pre>
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.
eventurl - the URL the platform sends event information asynchronously to when the callstatus changes
The product you want to access with this application. (Default: voice)
- --answermethod The http method for the answer_url. (Default: GET)
- --eventmethod The http method for the event_url. (Default: GET)
<pre><code class="lang-bash">> 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</code></pre>
Alias:
nexmo au.
Delete an application
Parameters:
app_id - The UUID of your application.
<pre><code class="lang-bash">> 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</code></pre>
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
<pre><code class="lang-bash">> 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</code></pre>
Alias:
nexmo an and nexmo apps:numbers.
Linking
Link a number to an app
<pre><code class="lang-bash">> nexmo link:app 12057200555 asdasdas-asdd-2344-2344-asdasdasd345 Number updated
> nexmo unlink:app 12057200555 Number updated</code></pre>
Alias:
nexmo la
Link a number to another phone number
<pre><code class="lang-bash">> nexmo link:tel 12057200555 4455555555 Number updated
> nexmo unlink:tel 12057200555 Number updated</code></pre>
Alias:
nexmo lt
Link a number to an SMS callback URL
<pre><code class="lang-bash">> nexmo link:sms 12057200555 http://example.com/callback Number updated
> nexmo unlink:sms 12057200555 Number updated</code></pre>
Alias:
nexmo lsms
Link a number to a Voice XML callback URL
<pre><code class="lang-bash">> nexmo link:vxml 12057200555 http://example.com/callback Number updated
> nexmo unlink:vxml 12057200555 Number updated</code></pre>
Alias:
nexmo lv
Link a number to SIP URI
<pre><code class="lang-bash">> nexmo link:sip 12057200555 sip:123@example.com Number updated
> nexmo unlink:sip 12057200555 Number updated</code></pre>
Alias:
nexmo lsip
Insight
Insight Basic
This is the free Number Insight API:
<pre><code class="lang-bash">> nexmo insight:basic 447555555555 447555555555 | GB</code></pre>
Alias:
nexmo insight and nexmo ib
Insight Standard
This API will charge your account but provide additional details:
<pre><code class="lang-bash">> nexmo insight:standard 447555555555 --confirm 447555555555 | GB | Telefonica UK Limited</code></pre>
Verbose mode will return additional information.
Alias:
nexmo is
Insight Advanced
This API will charge your account but provide additional details:
<pre><code class="lang-bash">> nexmo insight:advanced 447555555555 --confirm 447555555555 | GB | Telefonica UK Limited</code></pre>
Verbose mode will return additional information.
Alias:
nexmo ia
JWT
Generate
<pre><code class="lang-bash">jwt:generate [options] <private_key> [claim=value...]</code></pre>
Generate a JWT for your voice application.
<pre><code class="lang-bash">> nexmo jwt:generate path/to/private.key application_id=asdasdas-asdd-2344-2344-asdasdasd345</code></pre>
Generate a JWT for the Client SDK
<pre><code class="lang-bash">> nexmo jwt:generate path/to/private.key subject=username application_id=asdasdas-asdd-2344-2344-asdasdasd345</code></pre>
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.
<pre><code class="lang-bash">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</code></pre>
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][license]
[license]: LICENSE.txt
