Menu

Deploy and release using the Flex Plugins CLI

The twilio flex:plugins:deploy command automates the process of uploading your plugin to Flex. This allows you to deploy your plugins via the command line, without needing to manually upload them using a GUI. After a deploy, your plugin is not yet enabled for all your users on your Flex application. You need to run the release command after the deploy to enable any changes.

The twilio flex:plugins:release command is used to change which plugins are live for your users. You can group multiple plugins into a release, and you can re-activate any prior release to rollback changes.

This guide includes examples for deploying and releasing your Flex plugins.

Compatible CLI versions

You need to install the latest version of the Flex Plugins CLI in order to use these features. If you're migrating a legacy plugin to use the new CLI, refer to our Migration Guide.

Deploying a major version of a plugin

twilio flex:plugins:deploy --major --changelog "Notes for this version" --description "Functionality of the plugin"

The deploy command does the following:

  • It publishes your plugin as a Private Asset that is accessible by the Functions & Assets API. If you want to deploy your plugin as a Public Asset, you may pass --public to your deploy command.
  • It registers a new version of the plugin via the Plugins API. For the example above, the --major flag is passed. This creates a new major version of the plugin (ex: v1 to v2), and it stores the provided changelog along with your new version. If a version option (major, minor, or patch) is not provided, the deploy command defaults to a new patch version.
  • It updates the version field in the package.json of your plugin to the new version.
  • If the plugin is being deployed the first time, it also registers it as a new plugin with the provided description. The description option does not need to be provided on additional deploys.

Creating a new release

Releasing plugins is a two-step process using the Plugins API.

  1. You create a Flex Plugin Configuration. This contains the list of plugins you want active and their versions.
  2. You create a Flex Release with the configuration created in the previous step.

The Plugins CLI release command combines both of these steps to simplify the most common scenarios.

A) One-step release

You can create a release by listing each of the plugins that should be active for your users:

twilio flex:plugins:release --plugin plugin-agent-notes@9.0.0 --plugin plugin-name@version --name "Sprint 1" --description "Improving Integration with CRM"

The release command does the following:

When constructing a new release:

  • The --plugin argument takes the plugin you want to enable in the format plugin-name@version. Multiple plugins can be grouped into a release by using --plugin for each plugin that should be enabled.
  • We recommend setting the --name and --description options. These can be used to describe what changed within this release, and these details will be displayed within the Plugins Dashboard. These are a useful reference when reviewing your release history or choosing to re-deploy a prior release.

B) Separating your configuration and release

A new configuration does not need to be immediately released to users. You can instead create a configuration first and then pass in a reference to the configuration when creating a release. This is similar to the process you'll use to re-deploy a prior release.

First, create a new Flex Plugin Configuration:

twilio flex:plugins:create-configuration --name "Example config1" --description "Testing new plugins" --plugin plugin-test1@1.0.0 --plugin <plugin-name>@<version>​

This command will create a new configuration and return the SID of your new resource. You can lookup the SID of a configuration by running:

twilio flex:plugins:list:configurations​

Finally, create a new Release with your provided Flex Plugin Configuration:

twilio flex:plugins:release --configuration-sid <Configuration Sid>

Releasing multiple plugins

By default, the release and create-configuration commands will merge the list of plugins you provide with the plugins that are on the active configuration. This behavior can be changed with the --new argument. Suppose you have two plugins live: plugin-alpha@1.0.1 and plugin-beta@2.1.1. A new v1.1.0 version of plugin-alpha has been deployed, and you are creating a new release:

Without --new (default)

twilio flex:plugins:release --plugin plugin-alpha@1.1.0 --name "Bumping Alpha" --description "Alpha and Beta both up-to-date"

In this release, plugin-alpha is updated to the version provided in the command. plugin-beta stays enabled on the active version.

With --new

twilio flex:plugins:release --new --plugin plugin-alpha@1.1.0 --name "Removing Beta" --description "Bumping Alpha and disabling Beta"

In this release, only the provided plugins are added to this release's configuration. The end result will be that only plugin-alpha is enabled.

The --new argument must be used if you are disabling a plugin that is on the active configuration.

Managing multiple accounts

The Flex Plugins CLI uses your Twilio Account SID and Auth Token to deploy your plugins.

If you are deploying your plugins to multiple accounts, you will need to provide credentials for each account. You can create multiple profiles using the Twilio CLI to store multiple credentials, and then pass them through to your commands in a few ways:

Use a Profile Name

Let's say you have created a profile called stage. You can pass the profile name in the deploy command to use the designated account.

twilio flex:plugins:deploy -p stage

Switch Profiles

Alternatively, you may switch which profile is active using the Twilio CLI's profiles command. To see the full list of local profiles and choose a new active profile, run:

twilio profiles:list
twilio profiles:use <profile_name>

Environment Variables

New pairs of AccountSid and AuthToken credentials may also be provided as environment variables with the deploy command:

TWILIO_ACCOUNT_SID=ACxxx TWILIO_AUTH_TOKEN=abc123 twilio flex:plugins:deploy

This will use the provided credentials and save them in the keychain. If you have multiple accounts saved and you do not provide credentials along with your deploy command, then you will be prompted to select one:

? Select from one of the following Account Sids (Use arrow keys)
❯ AC0000000000000000000000000000000 
  AC0000000000000000000000000000001
  AC0000000000000000000000000000002

You can use the above commands to tie plugin deployment into a CI/CD pipeline. For example:

#!/bin/bash
# This script runs within your plugin directory
npm install
npm run test
npm run lint
TWILIO_ACCOUNT_SID=ACXXXX TWILIO_AUTH_TOKEN=pass123 twilio flex:plugins:deploy

Make sure to handle your AccountSid and Auth Token as environment variables or arguments passed into your scripts.

Next Steps

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 Community Forums or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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