Alibaba Cloud CLI:Manage and use plugins

Plugins package the API call capabilities of each cloud product into standalone executable programs that are uniformly scheduled by the CLI core. Key features include the following:

• On-demand installation: You can install only the plugins you need to reduce the size of the CLI.

• Independent updates: Plugins release versions independently. You do not need to upgrade the CLI core.

• Consistent naming: Commands and parameters use kebab-case, such as describe-instances and --accept-language.

• Simplified parameters: Low-level parameters are automatically serialized. You can use key-value pairs for input.

• Complete help: You can run the --help command to view parameter types, descriptions, and whether they are required.

Plugins are installed to the ~/.aliyun/plugins directory. The manifest.json file lists the installed plugins.

Plugin naming rules

Plugin names follow the aliyun-cli-<product-code> format. The product code is the same as the product code on Alibaba Cloud OpenAPI. Examples include the following:

You can use the full plugin name, such as aliyun-cli-ecs, or the product code, such as ecs, when you install, uninstall, or update a plugin. The names are not case-sensitive.

View and search plugins

You can view all available plugins in the remote index:

aliyun plugin list-remote

The following sample output is returned:

Total plugins available: 316

Name                                     Latest Version  Preview  Status         Local Version  Description
----                                     --------------  -------  ------         -------------  -----------
aliyun-cli-ecs                           0.1.0           No       Installed      0.1.0          Aliyun CLI plugin for Elastic Compute Service operations.
aliyun-cli-fc                            0.1.0           No       Installed      0.1.0          Aliyun CLI plugin for Function Compute 3.0 operations.
aliyun-cli-acc                           0.1.0           No       Not installed  -              Aliyun CLI plugin for acs operations.

To find the plugin that contains a specific command, you can use the search feature. The search feature supports prefix matching.

# Search for plugins containing ecs
aliyun plugin search ecs
# Search for commands that start with describe in the ecs product
aliyun plugin search "ecs describe"

Execute Installation

Run the following command to install a plugin:

aliyun plugin install --names ecs

After the installation is complete, you can run aliyun plugin list to confirm the result.

Name                Version             Description
----                -------             -----------
aliyun-cli-ecs      0.1.0               Aliyun CLI plugin for Elastic Compute Service operations.
aliyun-cli-fc       0.1.0               Aliyun CLI plugin for Function Compute 3.0 operations.

You can use the following optional parameters as needed:

Product plugins use kebab-case naming. The CLI passes credentials, such as AccessKey and Security Token Service token, and the region and timeout settings from your current profile to the plugin. Options such as --profile and --region are also available for plugin commands. You do not need to perform separate configurations.

The command format is as follows:

aliyun <product-code> <command> [--parameter-name value ...]

Usage examples

aliyun ecs --help

aliyun ecs describe-regions --help

......
  --accept-language         string, Filter results by Chinese, English, or Japanese. For more information, see [RFC
                            7231](https://tools.ietf.org/html/rfc7231). Valid values:
                            - zh-CN: Simplified Chinese.
                            - zh-TW: Traditional Chinese.
                            - en-US: English.
                            - ja: Japanese.
                            - fr: French.
                            - de: German.
                            - ko: Korean.
                            Default value: zh-CN
  --instance-charge-type    string, The billing method for the instance. For more information, see https://help.aliyun.
                            com/document_detail/25398.html. Valid values:
                            - PrePaid: Subscription. Confirm your account supports balance payment or credit payment. Otherwise, the error InvalidPayMethod occurs.
                            - PostPaid: Pay-as-you-go.
                            - SpotWithPriceLimit: Set a maximum price.
                            - SpotAsPriceGo: Let the system set the bid. The highest price is the pay-as-you-go price.
                            Default value: PostPaid
......

aliyun ecs describe-regions --accept-language zh-CN

{
  "Regions": {
     "Region": [
	{
	   "LocalName": "China (Qingdao)",
	   "RegionEndpoint": "ecs.cn-qingdao.aliyuncs.com",
	   "RegionId": "cn-qingdao"
			},
	{
	   "LocalName": "China (Beijing)",
	   "RegionEndpoint": "ecs.cn-beijing.aliyuncs.com",
	   "RegionId": "cn-beijing"
	},
......

Advanced usage

Name                Version             Description
----                -------             -----------
aliyun-cli-ecs      0.1.0               Aliyun CLI plugin for Elastic Compute Service operations.
aliyun-cli-ess      0.1.0               Aliyun CLI plugin for Auto Scaling operations with multi-version API support.
aliyun-cli-fc       0.1.0               Aliyun CLI plugin for Function Compute 3.0 operations.

# Add the environment variable and apply it
echo 'export ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22' >> ~/.bashrc
source ~/.bashrc

Update plugins

You can update the specified plugin:

aliyun plugin update --name ecs

You can update all installed plugins.

aliyun plugin update

Uninstall plugins

aliyun plugin uninstall --name ecs

How to enable

You can enable this feature by running the following command:

aliyun configure set --auto-plugin-install true

Or, enable by setting an environment variable (Linux example):

# Add the environment variable and apply it
echo 'export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true' >> ~/.bashrc
source ~/.bashrc

After you configure the settings, you can run aliyun configure get to verify the configuration.

To enable automatic installation of pre-release versions:

aliyun configure set --auto-plugin-install-enable-pre true

Or configure the setting using an environment variable. For example, on Linux:

# Add the environment variable and apply it
echo 'export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL_ENABLE_PRE=true' >> ~/.bashrc
source ~/.bashrc

Installation strategy

The command-line interface (CLI) selects policies based on the running environment.

The following is a sample output of an automatic installation:

# Run without ecs plugin installed
aliyun ecs describe-regions --accept-language zh-CN
# Automatic installation output
Plugin 'aliyun-cli-ecs' is required for command 'ecs describe-regions' but not installed.
Auto-installing plugin 'aliyun-cli-ecs' (including pre-release versions)...
Downloading aliyun-cli-ecs 0.1.0...
Plugin aliyun-cli-ecs 0.1.0 installed successfully!
......

Sample output for an interactive installation (automatic installation disabled):

# Run without ecs plugin installed
aliyun ecs describe-regions --accept-language zh-CN
# Interactive installation output
Plugin 'aliyun-cli-ecs' is required for command 'ecs describe-regions' but not installed.
Tip: Run 'aliyun configure set --auto-plugin-install true' to skip this prompt.
Do you want to install it? [Y/n]: y
Installing plugin 'aliyun-cli-ecs' (including pre-release versions)...
Downloading aliyun-cli-ecs 0.1.0...
Plugin aliyun-cli-ecs 0.1.0 installed successfully!
......

Plugin command reference

Plugin environment variables

You can use the following environment variables to control the behavior of plugins:

Plugin installation shows “no stable version available”

This message indicates that only pre-release versions are available for the plugin. To install a pre-release version, you can add the --enable-pre parameter to the installation command:

aliyun plugin install --names <plugin-name> --enable-pre