CLI General Usage

Spaces can optionally be used instead of colons when entering commands. These two commands are functionally identical:

twilio api:core:messages:list
twilio api core messages list


To issue CLI commands that include your Twilio credentials, you must first create a profile (a collection of settings). To create a profile, use:

twilio login

When you run twilio login (an alias for twilio profiles:create), it uses your Account SID and Auth Token to generate API keys, stores them in a configuration file, and associates them with the provided profile ID.

Your Account SID and Auth Token are accessible from the first page of the Twilio Console, under Account Info.

twilio-cli uses your Auth Token to generate API Keys for your new profile, but discards the token immediately afterwards and does not store it locally for security purposes.

Set an active profile

By default, the credentials associated with the "active" profile are used when you run a twilio-cli command that doesn't reference a specific profile to use.

To set a profile as "active", run:

twilio profiles:use PROFILE_ID

twilio login does not set the provided profile as "active". Use the instructions above to set a newly-created profile as the "active" profile.

Multiple Twilio accounts/profiles

To create additional profiles, run twilio login again, but provide a different profile ID. For example:

twilio login dev

To use non-active profiles with commands, include -p [profile id] in the command. This could look like:

twilio phone-numbers:list -p dev

Alternatively, as shown earlier, you may change the active profile with the twilio profiles:use command:

twilio profiles:use dev

To see the full list of local profiles (including which profile is active), run:

twilio profiles:list

To take advantage of Twilio's Global Infrastructure, you can specify the target Region for the profile using the --region flag. For example:

twilio login --region au1

twilio-cli does not currently support logging in with test credentials.

Migrate profiles from twilio-cli v2 to v3

With the release of twilio-cli v3, twilio-cli now stores all credentials and other profile data in a local configuration file instead of in your system keychain. As a result, twilio-cli v3 is unable to read credentials for existing profiles that were created using twilio-cli v2.

After upgrading from twilio-cli v2 to v3, recreate any existing profiles using the profiles:create command:

twilio profiles:create

After recreating your existing profiles, you may delete any credentials named "twilio-cli" from your system keychain.

Remove a profile

To remove a profile, use:

twilio profiles:remove PROFILE_ID

For example, if you want to remove the dev profile, you would execute twilio profiles:remove dev

Use environment variables instead of a profile

You can also use credentials stored in environment variables:

Option 1 (recommended)

  • TWILIO_ACCOUNT_SID = your Account SID from your console
  • TWILIO_API_KEY = an API Key SID created in your console
  • TWILIO_API_SECRET = the secret for the API Key (you would have received this when you created an API key)
  • (optional) TWILIO_REGION = the Region for the account (default is 'us1')

Option 2

  • TWILIO_ACCOUNT_SID = your Account SID from your console
  • TWILIO_AUTH_TOKEN = your Auth Token from your console
  • (optional) TWILIO_REGION = the Region for the account (default is 'us1')

Option 2 should only be used in cases where you are unable to make use of option 1 (which are uncommon).

Once these environment variables are set, a profile is not required to issue commands with twilio-cli.

Precedence of stored credentials

twilio-cli will attempt to load credentials in the following order of priority:

  1. From the profile specified with the -p parameter
  2. From environment variables, if set
  3. From the active profile

Specify Edge

To take advantage of Twilio's Global Infrastructure, authorization using profiles or environment variables both support a target Edge environment variable: TWILIO_EDGE


The twilio:config command enables you to list and set your twilio-cli configuration values.

List values

To see your current configuration including Edge, profiles, and active profile, use:

twilio config:list

If a configuration value is currently determined by an environment variable, such as TWILIO_EDGE, it will have [env] appended to its value. For example, this could look like:

$ export TWILIO_EDGE=sydney
$ twilio config:list
Config Name          Value
edge                 "sydney[env]"
# remaining config values...

Set values

To set a configuration value, such as setting your target Edge to sydney without an environment variable, use:

twilio config:set --edge=sydney

Remove values

To remove the value of a configuration that has previously been set, set the value to an empty string. You will be prompted to confirm that you want to remove that value from your configuration.

This is useful in case you are temporarily setting the Edge to a non-US location for some work, and want to revert back to the US Edge afterwards. As an example:

$ twilio config:set --edge=
? Remove existing edge value? Yes

Require profile input

To configure twilio-cli to reject any commands that do not include a profile flag, use:

$ twilio config:set --require-profile-input

# ❌ This is doomed to fail since no profile is provided
$ twilio phone-numbers:list
 » Error: Missing required flag:
 -p, --profile PROFILE  Shorthand identifier for your profile. To disable this check run:

  twilio config:set --no-require-profile-input

# ✅ profile is defined, request accepted
$ twilio phone-numbers:list --profile=dev
SID                                 Phone Number  Friendly Name
PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  +1646887XXXX  Congress hotline

# ✅ you can also use shorthand for the profile flag
$ twilio phone-numbers:list -p dev
SID                                 Phone Number  Friendly Name
PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  +1646887XXXX  Congress hotline

Run the following command and confirm to revert this setting:

$ twilio config:set --no-require-profile-input
? Overwrite existing requireProfileInput value? Yes

If no profile is active after setting --no-require-profile-input, run twilio profiles:use [profile id] to set an active profile for subsequent CLI commands.

Precedence of configuration values

twilio-cli will attempt to load configuration values in the following order of priority:

  1. From environment variables, if set
  2. From the values in config.json

Do not edit the twilio-cli configuration file (config.json) manually, as this may cause twilio-cli to break.


Instructions on how to create a Twilio subaccount can be found in the Twilio docs.

API commands

For non-twilio api:core commands, with your subaccount SID, please use profiles (via twilio login to create a new profile or twilio profiles to manage existing credentials).

API core commands

twilio-cli profiles created for parent accounts cannot be used to manage subaccounts as it creates a Standard API Key. An appropriate Main API Key can be created here.

Instead of using twilio login, you must use environment variables if you want access to subaccounts. There are two options (Master API Key, or Parent Account SID and Auth Token).

Once you have your subaccount SID, you can add the --account-sid parameter to run a command on a specific subaccount, provided it's a twilio api:core command.

For example:

Option 1 (recommended)

$ twilio api:core:available-phone-numbers:local:list \
    --area-code="415" \
    --country-code US \

Option 2

The Account SID and Auth Token can be retrieved from the console.

$ twilio api:core:available-phone-numbers:local:list \
    --area-code="415" \
    --country-code US \

Option 2 should only be used in cases where you are unable to make use of option 1 (which are uncommon).

Special features


You can set the webhook for a phone number like so:

twilio phone-numbers:update {PHONE_NUMBER_SID|E164} \

Replace {PHONE_NUMBER_SID|E164} with either the SID of your Twilio number (ex. PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX), or the E.164 formatted version of the phone number itself (ex. "+14155552671").

This sets the primary SMS url. There are also options for setting the voice url, fallback urls, and methods for each. Run twilio phone-numbers:update --help for a full list of options.

Proxying your localhost

When you set a webhook, if you specify a URL that uses the host name of localhost or, twilio-cli will automatically create a public proxy for you and set your webhook to the new proxy URL. For example:

twilio phone-numbers:update {PHONE_NUMBER_SID|E164} \
  --sms-url http://localhost:5000/handle_sms

Please be aware that this will temporarily expose your computer to the internet. You should exit this command when you have completed testing.

Output formats

All command output is sent to stdout (whereas logging messages are sent to stderr).

By default, the output is formatted in human readable form in a columnar format like so:

SID                                 Phone Number  Friendly Name
PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  +1209242XXXX  SIP testing
PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  +1646887XXXX  Congress hotline
PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  +1209337XXXX  DAVID'S TWILIO CONTACT

Many list commands will allow you to specify a --properties option to specify which columns you'd like to display. For example, to display only the Phone Number and SMS Url columns, you would pass --properties "phoneNumber, smsUrl".

Note that the default list of properties varies by command and is subject to change with each release. Use the --properties option to explicitly control which columns to output.

Also note that the column names must match the JSON property names in the Twilio API.

JSON output format

On any command, you can add -o json to change the output format to JSON. When you choose JSON, the command will send the entire API response to stdout as JSON. You can then pipe to tools like jq to parse the JSON.

Tab separated values

To change the output format to tab separated values (TSV), add -o tsv to the command line. This format is useful for loading into spreadsheets or for other machine processing. Like the default, columnar output format, you can use the --properties option to specify which columns you would like included.

Logging messages

All debug, informational, warning, and error information is sent to stderr. This is so it can be easily separated from the command output. You can decide what level of logging you'd like by using the -l option. The valid levels of logging messages are debug, info, warn, error, and none.


To enable autocomplete of CLI commands in bash or zsh, run:

twilio autocomplete

And follow the instructions.

Sending email with Twilio SendGrid

When you run twilio email:send you can send an email. You can use twilio email:set to set a default email address for the sender and default subject line. After you set those, twilio email:send will automatically use the default sending email address and subject line. To change the sending email address or subject line, you can either re-run twilio email:set or use the corresponding flag to set a new value for the item you want to change.

To send an email with an attachment run twilio email:send and wait to be prompted to add an attachment. You can also use twilio email:send --attachment=filePath to attach a file.

To send the output of a different command as an email attachment, pipe the command to twilio email:send. If a default sending email address and subject line has been set the command will automatically use the defaults and you only need to include the --text="email body text" and If there is not a default subject line and sender’s email address all the flags need to be included to send the output of the piped command.

Pipe output to email example

ps -aux | twilio email:send \
  --from="" \
  --to="" \
  --subject="Current processes" \
  --text="See attachment"


Installing a specific version of twilio-cli

To figure out what versions are available, consult the releases list.

Package managers


To install a specific version of twilio-cli with Homebrew, use:

brew install twilio@VERSION

Replace VERSION with the semantic version of the release you need—for example, 2.36.1:

brew install twilio@2.36.1

VERSION must be 2.36.1 or higher. This installation method does not support older versions.

Downgrade from an existing installation

If you have a newer version of twilio-cli already installed, you will need to unlink that installation so that your system can use the past version in subsequent commands:

brew unlink twilio && brew link twilio@VERSION

As we did earlier, replace VERSION with the semantic version of the release you need—for example, 2.36.1.

Restore to the latest version of twilio-cli

To restore your installation of twilio-cli to the latest version again, reverse the previous process and relink to the latest release:

brew unlink twilio@VERSION && brew link twilio

If you installed twilio-cli with any of the other common package managers (scoop, apt, or yum/dnf), uninstall your current version by following the respective Uninstall instructions for your operating system and package manager. Afterwards, follow the steps in the Platform executables section below to install a specific version.

Platform executables

If you installed twilio-cli with one of the platform executable files (.pkg, .exe, .deb, or .rpm):

  • From the releases list, find your desired version and click on Assets under that release to reveal its platform executables.
  • Download the executable for your operating system.
  • Install as described in the general installation instructions for your operating system.


If you installed twilio-cli with npm, use the following commands to install a specific version:

npm uninstall -g twilio-cli && npm install -g twilio-cli@VERSION

Replace VERSION with your desired version.

Known limitations

  • The default timeout value for Twilio API requests in twilio-cli is 30 seconds.
  • When listing resources, only the first 50 records will be displayed, by default. Use the --limit flag to modify this behavior.
    • You can filter these results based on date, to, from, etc. to further limit the results.
    • Pass the --help or -h flag to the command for details on which fields you may filter by.
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more