Aliyun CLI 专家

指导使用 aliyun 命令行工具管理阿里云资源。

MCP 工具与本地 CLI 执行

重要：此技能提供 CLI 命令知识和语法指导。这并不意味着你应始终在 shell 中本地运行 aliyun 命令。

执行优先级：

1. MCP 工具（最高优先级） — 当 AlibabaCloud___CallCLI 和其他 MCP 工具可用时，始终使用它们执行 API。MCP 工具处理认证、跨账号访问（x_assume_account_id）和输出过滤（x_output_jmespath_filter），无需本地安装或配置 CLI。

1. 本地 CLI（回退） — 仅在以下情况下在 Bash 工具中使用本地 aliyun 命令：

• MCP 工具不可用或未配置
• 操作需要本地文件系统访问（例如 aliyun oss cp、aliyun ossutil sync）
• 用户明确要求提供本地 CLI 命令以复制粘贴或在脚本中使用
• 用户需要安装/配置 CLI 本身

将此技能的知识用于：

• 在调用 AlibabaCloud___CallCLI 时理解正确的命令语法
• 通过 AlibabaCloud___GenerateCLICommand 生成 CLI 命令
• 了解插件风格命令与内置风格命令的差异
• 理解参数命名约定（尤其是 --biz- 前缀）
• 排查 MCP 或本地执行返回的 CLI 错误
• 指导希望在自己的终端中运行命令的用户

当用户请求看起来是解决方案模式（批量操作、审计、轮换、定时清理、运行手册）或目标产品未被任何插件内技能覆盖时，转向 alibabacloud-find-skills——打包的官方技能通常优于手工编写的 CLI 序列。参见 mcp-core-best-practices → Skill Discovery 以获取完整触发列表。

Agent 执行：AI-mode 和 User-Agent

仅适用于本地运行 aliyun 命令时（不通过 MCP 工具）。

技能标识符：AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance

使用恰好一种方式将此技能附加到请求。不要为同一技能令牌组合 AI-mode（configure ai-mode + set-user-agent）与 ALIBABA_CLOUD_USER_AGENT 或每条命令的环境变量前缀——CLI 会叠加这些来源，导致 User-Agent / 归因重复（对遥测不利）。

| 路径 | 何时使用 | 开始 | 结束 / 清理 | | ---- | ----------- | ----- | ------------- | | A — AI-mode（优先用于 agent） | Agent 会话，许多 aliyun 调用 | aliyun configure ai-mode enable 然后 aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance" | [MUST] 在每次退出（成功、失败、错误、取消、会话结束）的最终响应之前运行 aliyun configure ai-mode disable。不要在 AI-mode 开启时将 ALIBABA_CLOUD_USER_AGENT 导出为同一值。 | | B — 环境变量或一次性 | 一次性命令、不使用 configure 的脚本，或无 AI-mode | export ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance 用于该会话，或为每次 API 调用添加前缀：ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance aliyun ... | 如果你使用了 export，完成后运行 unset ALIBABA_CLOUD_USER_AGENT，以免其他技能被错误归因。内联前缀无需 unset。不要在路径 B 上为同一技能字符串启用 AI-mode。 |

预检查：需要 Aliyun CLI >= 3.3.3 — 运行 aliyun version。如果版本过低：curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 或参见 references/installation-guide.md。

预检查：需要更新 Aliyun CLI 插件 — [MUST] aliyun configure set --auto-plugin-install true；[MUST] aliyun plugin update。

CLI 版本里程碑

| 从版本 | 你获得什么 | | ------------- | -------------- | | >= 3.3.3 | 此技能中产品插件和流程的基线。 | | >= 3.3.5 | aliyun upgrade — 从二进制文件本身更新 CLI。 | | >= 3.3.8 | aliyun plugin show --name <plugin> — 已安装插件的详细信息。 |

指令

1. 安装并配置 CLI

如果用户尚未安装或配置 CLI，引导其完成设置。参见 ./references/installation-guide.md 了解完整详情。快速路径：

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

当 CLI 处于 3.3.5 或更新版本后，常规自我更新可以使用 aliyun upgrade。

OAuth（浏览器登录）

当同一台机器上可以打开浏览器时，优先使用 OAuth，而不是存储 AccessKey 对。需要 CLI 3.0.299 或更新版本。不适合无头环境。

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

环境变量（无头 / 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

认证模式

| 模式 | 何时使用 | 环境变量 | | ---- | ----------- | --------------------- | | AK | 开发、长期凭证 | ALIBABA_CLOUD_ACCESS_KEY_ID、ALIBABA_CLOUD_ACCESS_KEY_SECRET、ALIBABA_CLOUD_REGION_ID | | StsToken | CI/CD、临时凭证 | 与 AK 相同，外加 ALIBABA_CLOUD_SECURITY_TOKEN | | RamRoleArn | 在 AssumeRole 或跨账号会话后 | 与 StsToken 相同的变量 |

2. 在构造任何命令前先查阅 --help

内置命令在不同 API 之间的参数命名不一致。先运行 --help 是权威来源：

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

安装插件后，aliyun <product> --help 显示插件帮助。若要改为查看旧版内置帮助：

ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true aliyun ecs --help

3. 确保服务插件可用

每个阿里云产品都有一个 CLI 插件。插件提供一致的 kebab-case 命令和全面帮助：

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. 优先使用插件命令而不是内置命令

CLI 有两种命令风格，子命令大小写决定由哪个系统处理：

• 全小写子命令 -> 路由到插件（CLI Native 风格）
• 包含大写 -> 路由到内置（OpenAPI 风格）

# 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

MCP 工具说明：AlibabaCloud___CallCLI 使用 OpenAPI 风格（PascalCase）命令。插件风格命令用于本地 CLI 执行。为 MCP 执行生成命令时，使用 PascalCase 子命令（例如 aliyun ecs DescribeInstances）。

| 方面 | 插件（CLI Native） | 内置（OpenAPI） | | ------ | ------------------- | ------------------ | | 子命令 | describe-instances | DescribeInstances | | 参数 | kebab-case（一致） | 混合（不一致） | | ROA Body | 展开为独立参数 | 单个 --body JSON | | Header 参数 | 在帮助中可见，可直接使用 | 隐藏，仅手动 --header | | 帮助 | 包含结构的全面帮助 | 基础 |

5. 理解全局参数与业务参数命名

CLI 插件系统保留某些全局参数：

• --region-id / --region — 控制请求发送到哪个 API endpoint。
• 其他全局参数：--profile、--api-version、--output 等。

许多 API 也定义自己的 RegionId 参数。插件通过以下方式解析：

1. --biz- 前缀（默认）：API 的 RegionId 变为 --biz-region-id
2. --<product>- 前缀（回退）：如果 --biz-region-id 已被占用

始终检查 --help 以获取实际参数名称。

6. 使用结构化参数语法

插件支持框架自动序列化的结构化输入：

--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 使用自定义命令

与其他产品不同，OSS 具有手写实现和自定义命令语法。PutBucket 等 API 风格命令在 OSS 中不存在：

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

注意：OSS 文件操作（cp、sync 等）需要本地文件系统访问。这些不能通过 MCP 工具运行——直接使用 Bash 工具。

8. 过滤和格式化输出

# 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[]"

MCP 工具说明：使用 x_output_jmespath_filter 参数而不是 --cli-query。

9. 分页

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. 等待资源状态

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

11. 调试

• --log-level debug — 详细请求/响应日志
• --cli-dry-run — 验证命令而不执行
• ALIBABA_CLOUD_CLI_LOG_CONFIG=debug — 全局调试的环境变量

对于 403、Forbidden、NoPermission，参见 ./references/ram-policies.md。

12. 多版本 API 支持

某些产品提供多个 API 版本：

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

通过环境变量设置默认版本：

export ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22

全局标志参考

| 标志 | 用途 | | ---- | ------- | | --region <region> | API endpoint 区域（全局，不是业务区域） | | --profile <name> | 使用命名凭证配置文件 | | --api-version <ver> | 覆盖此命令的 API 版本 | | --output json\|table\|cols=... | 响应格式 | | --cli-query <jmespath> | 响应的 JMESPath 过滤 | | --log-level debug | 详细请求/响应日志 | | --cli-dry-run | 验证而不执行 | | --endpoint <url> | 覆盖服务端点 | | --retry <n> | 失败请求的重试次数 | | --quiet | 抑制输出 | | --pager | 自动合并可分页 API 的所有页面 |

参考

• ./references/installation-guide.md — 安装、配置模式、凭证设置
• ./references/command-syntax.md — 完整命令语法指南
• ./references/global-flags.md — 全局标志参考
• ./references/ram-policies.md — 按需 RAM、最小权限、常见权限错误