Twilio CLI

When executing a command, twilio-cli resolves credentials in the following order of priority:

1. The profile explicitly specified with the -p parameter.
2. Environment variables (if set).
3. The currently active profile.

The Twilio CLI separates data from metadata:

• stdout: Contains the actual command output (e.g., the list of phone numbers).
• stderr: Contains all debug, informational, warning, and error messages. This allows you to pipe or process stdout without interference from logs.

Log Levels You can set a log level to control the verbosity of messages sent to stderr. The default level is info.

The Twilio CLI uses profiles to store credentials for different accounts. The first profile created becomes the 'active' profile used for all subsequent commands.

• Create a profile: Run twilio login (alias for twilio profiles:create).
• Switch active profile: Use twilio profiles:use <profile_id>.
• List profiles: Use twilio profiles:list to see all local profiles and identify the active one.
• Use a specific profile for a command: Use the -p flag (e.g., twilio phone-numbers:list -p my_other_profile).
• Specify Region: Use the --region flag during login to target a specific Twilio Region (e.g., twilio login --region au1).

twilio login
twilio profiles:use my_other_profile
twilio phone-numbers:list -p my_other_profile

The Twilio CLI uses a "multi-command" architecture similar to git. Commands are organized into topics to represent API resources, while the commands themselves represent actions performed on those resources.

• Single commands: e.g., twilio help.
• Topic + Command: e.g., twilio profile:add or twilio incoming-phone-number:list.
• Nesting: Topics and commands can be separated by a colon (:) or a space. Deeply nested resources follow the pattern twilio <topic>:<sub-topic>:<action>.

Example Mapping: If the resource is api:messaging:v1:services, the available actions (commands) would be create, fetch, list, update, and delete. The full command would look like: twilio api:messaging:v1:services:create.

# Example of a nested command structure
twilio api:messaging:v1:services:create

The twilio-cli follows a modified Semantic Versioning (MAJOR.MINOR.PATCH) pattern. To ensure stability in your automation or development environments, it is strongly recommended to pin at least the major version (and ideally the minor version) to prevent unexpected breaking changes.

• PATCH (MAJOR.MINOR.PATCH): Incremented for backwards-compatible bug fixes. These are generally safe to upgrade.
• MINOR (MAJOR.MINOR.PATCH): Incremented for new features or small backwards-incompatible changes (e.g., changes to specific commands). Upgrading may require manual code adjustments.
• MAJOR (MAJOR.MINOR.PATCH): Incremented for significant breaking changes or new technology families. These require extensive reworking of code and are communicated in advance via Release Candidates.

Be aware of the following default constraints:

• API Timeout: The default timeout for Twilio API requests is 30 seconds.
• List Limits: By default, list commands only display the first 50 records. Use the --limit flag to increase this number. You can also use available filters (e.g., date, to, from) to narrow down results.

When adding commands to src/commands, you must inherit from one of the following base classes to ensure proper integration with the CLI:

TwilioClientCommand

Use this if your command needs to make Twilio API calls.

• this.twilioClient: An instance of the Twilio Node.js helper library, pre-configured with necessary credentials and account SID.
• this.httpClient: Provided for making requests to non-Twilio APIs (you must manage credentials for these manually).

TwilioBaseCommand

Use this if your command does not need to make any Twilio API calls.

To use the Twilio CLI, ensure you meet the runtime requirements and follow the official setup documentation.

Requirements

• Node.js: Node 22+ is currently supported. The CLI supports LTS versions of Node.
• Note on Node 20: As of version 7.0.0, Node 20 is no longer supported. If you are on Node 20, you must upgrade to Node 22 or later.

Setup

For detailed installation instructions, refer to the Twilio CLI documentation.

The Twilio CLI follows traditional Unix-style command-line parameter conventions:

• Shorthand: Single dash and single letter (e.g., -f).
• Kebab-case: Two dashes and kebab-case names (e.g., --phone-number).

The CLI supports piping, allowing you to chain commands together. For example, you can find a phone number and then pipe that result into a command to purchase it.

Once your plugin is ready, you can distribute it in two ways:

Via NPM (Public)

1. Publish your package to npmjs.org using npm publish.
2. Users can install it using:

   twilio plugins:install <npm-package-name>

### Via Tarball (Private)
If you want to keep the package private:
1. Run `npm pack` to create a `.tgz` tarball.
2. Host the tarball (e.g., using Twilio Assets).
3. Users can install it using the URL:
   ```bash
twilio plugins:install <url_to_package.tar.gz>