From alibabacloud-core
Guide for Alibaba Cloud CLI (aliyun) command syntax, plugin system, parameter naming, and best practices. Use this skill to generate correct CLI commands, understand plugin vs built-in command differences, structured parameter syntax, output filtering, pagination, and error troubleshooting. This skill is a CLI knowledge reference — when MCP tools (AlibabaCloud___CallCLI, etc.) are available, always prefer MCP tools for execution rather than running aliyun commands locally in the shell.
How this skill is triggered — by the user, by Claude, or both
Slash command
/alibabacloud-core:alibabacloud-cli-guidanceThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Guide for managing Alibaba Cloud resources using the `aliyun` command-line tool.
Guide for managing Alibaba Cloud resources using the aliyun command-line tool.
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:
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.
Local CLI (fallback) — Only use local aliyun commands in the Bash tool when:
aliyun oss cp, aliyun ossutil sync)Use this skill's knowledge for:
AlibabaCloud___CallCLIAlibabaCloud___GenerateCLICommand--biz- prefixes)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.
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).
| Path | When to use | Start | End / cleanup |
|---|---|---|---|
| A — AI-mode (preferred for agents) | Agent session, many aliyun calls | aliyun configure ai-mode enable then aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance" | [MUST] aliyun configure ai-mode disable before the final response on every exit (success, failure, error, cancel, session end). Do not export ALIBABA_CLOUD_USER_AGENT to the same value while AI-mode is on. |
| B — Environment or one-shot | One-off commands, scripts without configure, or no AI-mode | export ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance for the session, or prefix each API call: ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance aliyun ... | If you used export, run unset ALIBABA_CLOUD_USER_AGENT when done so other skills are not mis-attributed. Inline prefix needs no unset. Do not enable AI-mode on path B for the same skill string. |
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.
| From version | What you gain |
|---|---|
| >= 3.3.3 | Baseline for product plugins and flows in this skill. |
| >= 3.3.5 | aliyun upgrade — update the CLI from the binary itself. |
| >= 3.3.8 | aliyun plugin show --name <plugin> — details for an installed plugin. |
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.
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
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
| Mode | When to use | Environment variables |
|---|---|---|
| AK | Development, long-lived credentials | ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, ALIBABA_CLOUD_REGION_ID |
| StsToken | CI/CD, temporary credentials | Same as AK, plus ALIBABA_CLOUD_SECURITY_TOKEN |
| RamRoleArn | After AssumeRole or cross-account session | Same variables as StsToken |
--help Before Constructing Any CommandBuilt-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
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
The CLI has two command styles, and the subcommand casing determines which system handles it:
# 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).
| Aspect | Plugin (CLI Native) | Built-in (OpenAPI) |
|---|---|---|
| Subcommand | describe-instances | DescribeInstances |
| Parameters | kebab-case (consistent) | Mixed (inconsistent) |
| ROA Body | Expanded to individual params | Single --body JSON |
| Header params | Visible in help, usable directly | Hidden, manual --header only |
| Help | Comprehensive with structure | Basic |
The CLI plugin system reserves certain global parameters:
--region-id / --region — controls which API endpoint the request is sent to.--profile, --api-version, --output, etc.Many APIs also define their own RegionId parameter. The plugin resolves this with:
--biz- prefix (default): API's RegionId becomes --biz-region-id--<product>- prefix (fallback): if --biz-region-id is already takenAlways check --help for the actual parameter name.
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)
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.
# 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.
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
aliyun vpc describe-vpc-attribute \
--biz-region-id cn-shanghai \
--vpc-id <your-vpc-id> \
--waiter expr='Status' to='Available'
--log-level debug — detailed request/response logs--cli-dry-run — validate command without executingALIBABA_CLOUD_CLI_LOG_CONFIG=debug — environment variable for global debugFor 403, Forbidden, NoPermission, see ./references/ram-policies.md.
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
| Flag | Purpose |
|---|---|
--region <region> | API endpoint region (global, not business region) |
--profile <name> | Use a named credential profile |
--api-version <ver> | Override API version for this command |
--output json|table|cols=... | Response format |
--cli-query <jmespath> | JMESPath filter on response |
--log-level debug | Verbose request/response logging |
--cli-dry-run | Validate without executing |
--endpoint <url> | Override service endpoint |
--retry <n> | Retry count for failed requests |
--quiet | Suppress output |
--pager | Auto-merge all pages for pageable APIs |
./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 errorsnpx claudepluginhub acloudlabs-unofficial/alibabacloud-agent-toolkit --plugin alibabacloud-coreCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.