Manage and use Alibaba Cloud CLI plugins

Plugin naming convention

Plugins follow the naming format aliyun-cli-<ProductCode>, where the product code matches Alibaba Cloud OpenAPI:

You can use either the full name (aliyun-cli-ecs) or product code (ecs). Names are case-insensitive.

Check plugin availability

Check whether a cloud product has a plugin:

• Online query (recommended): Browse by category, search by keyword, and view command examples in the CLI Center.

• Command-line query: List available plugins or search by keyword:

  • List all plugins in the remote index:

    aliyun plugin list-remote

  • Example output:

    Total plugins available: 316
    
    Name                                     Latest Version  Preview  Status         Local Version  Description
    ----                                     --------------  -------  ------         -------------  -----------
    aliyun-cli-ecs                           0.1.0           No       Installed      0.1.0          Alibaba Cloud CLI plugin for ECS operations.
    aliyun-cli-fc                            0.1.0           No       Installed      0.1.0          Alibaba Cloud CLI plugin for FC 3.0 operations.
    aliyun-cli-acc                           0.1.0           No       Not installed  -              Alibaba Cloud CLI plugin for acs operations.

Search for a plugin

Find which plugin provides a specific command. Prefix matching is supported.

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

Install a plugin

aliyun plugin install accepts a plugin via --name (e.g. aliyun plugin install --name ecs) or a positional argument (e.g. aliyun plugin install ecs). Both are equivalent. --name was added in v3.3.14.

Examples:

# Install a single plugin by name
aliyun plugin install --name ecs

# Install a specific version
aliyun plugin install --name fc --version 1.0.0

# Install multiple plugins at once
aliyun plugin install --names ecs rds vpc

# Install from a local archive file (for offline environments)
aliyun plugin install --package /path/to/ecs-plugin.zip

# Install from a URL
aliyun plugin install --package https://example.com/plugins/ecs-plugin.tar.gz

Verify with aliyun plugin list:

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.

Plugin commands use kebab-case. The CLI passes credentials, region, and timeout from the current profile automatically. Global options like --profile and --region apply without extra configuration.

Command format:

aliyun <plugin-name> <Command> [--parameter-name value ...]

Usage examples

aliyun ecs --help

aliyun ecs describe-regions --help

......
  --accept-language         string, Filters the results by language. 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: en-US
  --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. If you use this method, make sure your account supports balance payments or credit payments.
                            Otherwise, an `InvalidPayMethod` error is reported.
                            - PostPaid: Pay-As-You-Go.
                            - SpotWithPriceLimit: A user-defined maximum price for a spot instance.
                            - SpotAsPriceGo: The system automatically bids for a spot instance at the Pay-As-You-Go price.
                            Default: PostPaid
......

aliyun ecs describe-regions --accept-language en-US

{
  "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               Alibaba Cloud CLI plugin for ECS operations.
aliyun-cli-ess      0.1.0               Alibaba Cloud CLI plugin for Auto Scaling operations with multi-version API support.
aliyun-cli-fc       0.1.0               Alibaba Cloud CLI plugin for FC 3.0 operations.

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

Update a plugin

Update a specific plugin:

aliyun plugin update --name ecs

Update all installed plugins:

aliyun plugin update

If already at the latest version, the CLI reports no update needed. Add --enable-pre for pre-release versions.

Verify with aliyun plugin list.

Uninstall a plugin

Remove a plugin:

aliyun plugin uninstall --name ecs

Verify removal with aliyun plugin list.

Enable automatic installation

Enable via command:

aliyun configure set --auto-plugin-install true

Or with an environment variable:

echo 'export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true' >> ~/.bashrc
source ~/.bashrc

Verify with aliyun configure get.

Allow pre-release auto-installation:

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

Or with an environment variable:

echo 'export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL_ENABLE_PRE=true' >> ~/.bashrc
source ~/.bashrc

Installation policy

Behavior varies by runtime environment:

Example output for automatic installation:

# Run a command when the ecs plugin is not installed
aliyun ecs describe-regions --accept-language en-US
# Output of the automatic installation process
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!
......

Example output in an interactive environment with auto-install disabled:

# Run a command when the ecs plugin is not installed
aliyun ecs describe-regions --accept-language en-US
# Output of the interactive installation process
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!
......

View current settings

View current settings:

aliyun configure plugin-settings show

Set a custom plugin source

Set a custom source URL:

aliyun configure plugin-settings set --source-base https://internal-mirror.example.com/cli-plugins

Verify:

aliyun configure plugin-settings show

Clear custom settings

Clear custom settings and restore defaults:

aliyun configure plugin-settings clear

Source URL priority

The CLI resolves the source URL in this order (first match wins):

1. The --source-base flag on the current command.

2. The ALIBABA_CLOUD_CLI_PLUGIN_SOURCE_BASE environment variable.

3. The source-base value in ~/.aliyun/plugin-settings.json.

4. The built-in default URL.

Plugin command list

Plugin environment variables

Environment variables for plugin behavior:

Installation fails: "no stable version available"

The plugin has only pre-release versions. Add --enable-pre:

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