Alibaba Cloud CLI:Migrate from legacy to plugin-based Alibaba Cloud CLI

Comparison example

For the DescribeRegions API, the plugin-based command is:

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

The legacy command is:

aliyun ecs DescribeRegions --AcceptLanguage zh-CN

Here the only change is naming convention, but some plugin commands redesign parameters entirely — for example, --biz-region-id instead of --region-id, not a simple case conversion of the legacy --RegionId. Always verify parameter names with <command> --help or OpenAPI Explorer.

Core differences

Run the following command to check your version. If the result is 3.3.0 or later, your CLI already supports plugin-based commands. Otherwise, upgrade first.

aliyun version

To check whether a specific command uses the plugin-based or legacy version, run aliyun <command> <sub-command> --help:

• Plugin-based version: The help output includes a global parameters section, and parameter names typically use the kebab-case style (for example, --region-id).

• Legacy version: The help output includes only a parameters section, and parameter names typically use the PascalCase style (for example, --RegionId).

Search using OpenAPI Explorer

When you know the legacy command name (the API action name), this is the most direct method:

1. Open OpenAPI Explorer.

2. In the search box, enter the legacy command name (for example, DescribeInstances). The search results list the matching APIs.

3. Click the target API to go to its details page, fill in the required parameter values, and then switch to the CLI Example tab on the right.

4. The plugin-based command is displayed under CLI Style (New), and the legacy command is displayed under API Native Style (Old). Copy the new command to replace the old one in your script.

Browse CLI home page

The CLI homepage on OpenAPI Explorer lists all supported plugin-based commands organized by cloud service, along with parameter descriptions.

Discover commands with --help

After installing a cloud service plugin, use --help at each level to browse available commands and parameters. For example, to view all ECS plugin commands:

aliyun ecs --help

To view usage and parameters for a specific command:

aliyun ecs describe-instances --help

Query using CLI Skills

Visit CLI Skills, install the skill, and describe your requirements in natural language through an agent to get the corresponding plugin-based command.

Step 1: Upgrade the CLI

Check your current version:

aliyun version

If the version is earlier than 3.3.0, follow Install and update Alibaba Cloud CLI to upgrade. You do not need to uninstall the legacy version — your credential configuration (~/.aliyun/config.json) is preserved.

After upgrading, legacy commands still work. New features, product support, and security fixes ship only in the plugin-based version.

Step 2: Install plugins

Install the cloud service plugins you need:

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

# Install multiple plugins
aliyun plugin install --names ecs oss vpc

Alternatively, enable automatic plugin installation. When you run a command whose plugin is missing, the CLI installs it automatically:

export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true

Step 3: Verify a command

Run a plugin-based command to verify that everything works:

aliyun ecs describe-regions

A JSON list of regions confirms the plugin-based CLI is working.

Step 4: Update your scripts

Gradually replace the legacy commands in your scripts with the plugin-based syntax:

1. Identify legacy commands in your scripts. A common sign is that the second argument uses PascalCase (for example, aliyun ecs DescribeInstances).

2. Search for the legacy command name in OpenAPI Explorer to find its plugin-based equivalent.

3. Replace the legacy command with the plugin-based equivalent, and update parameter names accordingly.

4. Test the updated script.

Legacy commands remain functional in the new version, so you can migrate in batches based on priority.

CI/CD pipelines

In non-interactive environments, the CLI cannot prompt for plugin installation. Use one of these approaches:

• Pre-install the plugins in your pipeline script:

  aliyun plugin install --names ecs oss vpc

• Or, set an environment variable to enable automatic installation:

  export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true

Add this variable to your pipeline's global environment configuration (the environment block in a Jenkinsfile or the env section in GitHub Actions) so it applies to every build.

Output parsing scripts

Plugin-based commands may return different JSON structures than legacy commands, which pass through raw API responses. If your scripts parse output with jq, grep, or similar tools, verify the output format after switching.

Complex command migration

Commands with complex parameters are the most error-prone part of migration.

aliyun slb AddBackendServers \
  --LoadBalancerId lb-xxx \
  --BackendServers '[{"ServerId":"i-aaa","Weight":100},{"ServerId":"i-bbb","Weight":80}]'

aliyun slb add-backend-servers \
  --load-balancer-id lb-xxx \
  --backend-servers '[{"ServerId":"i-aaa","Weight":100},{"ServerId":"i-bbb","Weight":80}]'

aliyun ecs run-instances \
  --region cn-hangzhou \
  --instance-type ecs.g7.large \
  --image-id ubuntu_22_04_x64_20G_alibase_20230China.vhd \
  --security-group-id sg-xxx \
  --vswitch-id vsw-xxx \
  --system-disk "$(cat <<'EOF'
{"Size":40,"Category":"cloud_essd","PerformanceLevel":"PL1"}
EOF
)"

aliyun ecs DescribeInstances --RegionId cn-hangzhou \
  | jq -r '.Instances.Instance[] | select(.Status=="Running") | .InstanceId'

# Plugin-based version: first, check the output structure, then adjust the jq expression.
aliyun ecs describe-instances --region cn-hangzhou \
  | jq -r '.Instances.Instance[] | select(.Status=="Running") | .InstanceId'

Viewing legacy help

After installing a product plugin, aliyun <command> --help shows plugin help by default. To view legacy help instead, set:

export ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true

Can I still use legacy PascalCase commands after upgrading?

Yes. Versions 3.3.0 and later are backward-compatible. However, only the plugin-based version receives new features and fixes.

Do I need to reconfigure credentials after migration?

No. The plugin-based CLI shares the same credential store (~/.aliyun/config.json). All profile entries and environment variable credentials carry over.

Can I mix legacy and plugin-based commands in the same script?

Yes. Both styles coexist in the same script. Replace legacy commands gradually based on priority.

What if plugin installation fails?

Troubleshoot in this order:

1. Check whether your network can access aliyuncli.alicdn.com.

2. Verify that the plugin installation directory (~/.aliyun/plugins/) has write permissions.

3. Confirm that your CLI version is 3.3.0 or later (earlier versions do not support plugins). Run aliyun version to check.