Alibabacloud CLI Guidance

Aliyun CLI Expert

Guide for managing Alibaba Cloud resources using the aliyun command-line tool.

MCP Tools vs Local CLI Execution

IMPORTANT: This skill provides CLI command knowledge and syntax guidance. It does NOT mean you should always run aliyun commands locally in the shell.

Execution priority:

1. MCP tools (highest priority) — When AlibabaCloud___CallCLI and other MCP tools are available, always use them for API execution. MCP tools handle authentication, cross-account access (x_assume_account_id), and output filtering (x_output_jmespath_filter) without requiring local CLI installation or configuration.

2. Local CLI (fallback) — Only use local aliyun commands in the Bash tool when:

   • MCP tools are not available or not configured
   • The operation requires local file system access (e.g., aliyun oss cp, aliyun ossutil sync)
   • The user explicitly asks for a local CLI command to copy/paste or use in scripts
   • The user needs to install/configure the CLI itself

Use this skill's knowledge for:

• Understanding correct command syntax when calling AlibabaCloud___CallCLI
• Generating CLI commands via AlibabaCloud___GenerateCLICommand
• Knowing the difference between plugin-style and built-in-style commands
• Understanding parameter naming conventions (especially --biz- prefixes)
• Troubleshooting CLI errors returned by MCP or local execution
• Guiding users who want to run commands locally in their own terminals

Pivot to alibabacloud-find-skills when: the user's request reads as a solution pattern (batch ops, audits, rotations, scheduled cleanup, runbooks) or targets a product not covered by any in-plugin skill — a packaged official skill usually beats hand-rolled CLI sequences. See mcp-core-best-practices → Skill Discovery for the full trigger list.

Agent Execution: AI-mode and User-Agent

Only applicable when running aliyun commands locally (not via MCP tools).

Skill identifier: AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance

Use exactly one way to attach this skill to requests. Do not combine AI-mode (configure ai-mode + set-user-agent) with ALIBABA_CLOUD_USER_AGENT or a per-command env prefix for the same skill token — the CLI stacks those sources, and User-Agent / attribution will duplicate (bad for telemetry).

Pre-check: Aliyun CLI >= 3.3.3 required — Run aliyun version. If too low: curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash or see references/installation-guide.md.

Pre-check: Aliyun CLI plugin update required — [MUST] aliyun configure set --auto-plugin-install true; [MUST] aliyun plugin update.

CLI Version Milestones

Instructions

1. Install and Configure the CLI

If the user hasn't installed or configured the CLI, guide them through setup. See ./references/installation-guide.md for full details. Quick path:

# Install or update (macOS / Linux — one command)
/bin/bash -c "$(curl -fsSL --connect-timeout 10 --max-time 120 https://aliyuncli.alicdn.com/setup.sh)"

After the CLI is at 3.3.5 or newer, routine self-updates can use aliyun upgrade.

OAuth (browser login)

When a browser can be opened on the same machine, prefer OAuth over storing AccessKey pairs. Requires CLI 3.0.299 or later. Not suitable for headless environments.

aliyun configure --profile <your-profile-name> --mode OAuth

Environment variables (headless / CI/CD)

export ALIBABA_CLOUD_ACCESS_KEY_ID=<key-id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<key-secret>
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou
# Temporary credentials (StsToken) — add:
# export ALIBABA_CLOUD_SECURITY_TOKEN=<sts-token>

# Verify
aliyun version      # Should be >= 3.3.3
aliyun ecs describe-regions   # Tests authentication

Authentication modes

2. Consult --help Before Constructing Any Command

Built-in commands have inconsistent parameter naming across APIs. Running --help first is the authoritative source:

aliyun <product> --help                # Discover available subcommands
aliyun <product> <subcommand> --help   # Get exact parameter names, types, structure

When a plugin is installed, aliyun <product> --help shows plugin help. To view legacy built-in help instead:

ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true aliyun ecs --help

3. Ensure Service Plugins Are Available

Each Alibaba Cloud product has a CLI plugin. Plugins provide consistent kebab-case commands with comprehensive help:

aliyun plugin install --names ecs     # Install (short name, case-insensitive)
aliyun plugin install --names ECS VPC RDS   # Multiple at once
aliyun plugin list                    # Installed plugins
aliyun plugin list-remote             # All available plugins
aliyun plugin search <keyword>        # Search by keyword
aliyun plugin show --name ecs         # >= 3.3.8 — details for one installed plugin

4. Prefer Plugin Commands Over Built-in Commands

The CLI has two command styles, and the subcommand casing determines which system handles it:

• All-lowercase subcommand -> routed to plugin (CLI Native style)
• Contains uppercase -> routed to built-in (OpenAPI style)

# Plugin (preferred): consistent kebab-case
aliyun ecs describe-instances --biz-region-id cn-hangzhou

# Built-in (fallback): PascalCase subcommand, inconsistent params
aliyun ecs DescribeInstances --RegionId cn-hangzhou

Note for MCP tools: AlibabaCloud___CallCLI uses OpenAPI-style (PascalCase) commands. The plugin-style commands are for local CLI execution. When generating commands for MCP execution, use PascalCase subcommands (e.g., aliyun ecs DescribeInstances).

5. Understand Global vs Business Parameter Naming

The CLI plugin system reserves certain global parameters:

• --region-id / --region — controls which API endpoint the request is sent to.
• Other globals: --profile, --api-version, --output, etc.

Many APIs also define their own RegionId parameter. The plugin resolves this with:

1. --biz- prefix (default): API's RegionId becomes --biz-region-id
2. --<product>- prefix (fallback): if --biz-region-id is already taken

Always check --help for the actual parameter name.

6. Use Structured Parameter Syntax

Plugins support structured input that the framework serializes automatically:

--instance-id i-abc123                                  # single value
--security-group-ids sg-001 sg-002 sg-003               # space-separated list
--tag Key=env Value=prod --tag Key=app Value=web        # repeatable key-value
--data-disk '{"DiskName":"d1","Size":100}'              # complex structure (JSON)

7. OSS Uses Custom Commands

Unlike other products, OSS has a hand-written implementation with custom command syntax. API-style commands like PutBucket do not exist for OSS:

aliyun oss --help        # Basic operations (cp, ls, mb, rm, etc.)
aliyun ossutil --help    # Advanced utilities (sync, stat, etc.)

Note: OSS file operations (cp, sync, etc.) require local file system access. These cannot be run via MCP tools — use the Bash tool directly.

8. Filter and Format Output

# JMESPath filter
aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --cli-query "Instances.Instance[?Status=='Running'].{ID:InstanceId,Name:InstanceName}"

# Output formats
aliyun ecs describe-instances --biz-region-id cn-hangzhou --output table
aliyun ecs describe-instances --biz-region-id cn-hangzhou --output cols=InstanceId,InstanceName,Status rows="Instances.Instance[]"

Note for MCP tools: Use x_output_jmespath_filter parameter instead of --cli-query.

9. Pagination

aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --page-number 1 \
  --page-size 50

# Auto-paginate all pages
aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --pager path='Instances.Instance[]' PageNumber=PageNumber PageSize=PageSize

10. Wait for Resource State

aliyun vpc describe-vpc-attribute \
  --biz-region-id cn-shanghai \
  --vpc-id <your-vpc-id> \
  --waiter expr='Status' to='Available'

11. Debugging

• --log-level debug — detailed request/response logs
• --cli-dry-run — validate command without executing
• ALIBABA_CLOUD_CLI_LOG_CONFIG=debug — environment variable for global debug

For 403, Forbidden, NoPermission, see ./references/ram-policies.md.

12. Multi-Version API Support

Some products ship multiple API versions:

aliyun <product> list-api-versions
aliyun ess describe-scaling-groups --api-version 2022-02-22 --biz-region-id cn-hangzhou

Set default version via environment variable:

export ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22

Global Flags Reference

References

• ./references/installation-guide.md — Installation, configuration modes, credential setup
• ./references/command-syntax.md — Complete command syntax guide
• ./references/global-flags.md — Global flags reference
• ./references/ram-policies.md — On-demand RAM, least privilege, common permission errors