阿里云 CLI 专家

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

所需权限：请参阅 ./references/ram-policies.md（## required_permissions）。针对其他 CLI 命令，按需扩展权限。

说明

Agent 执行：AI 模式和 User-Agent（此 skill）

Skill 标识符（无论使用哪条路径，字符串均相同）：AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance

只能使用一种方式将此 skill 附加到请求。对于同一个 skill 令牌，不得将 AI 模式（configure ai-mode + set-user-agent）与 ALIBABA_CLOUD_USER_AGENT 或单命令环境变量前缀结合使用，因为 CLI 会叠加这些来源，导致 User-Agent / 归因信息重复（不利于遥测）。

| 路径 | 适用场景 | 启动 | 结束 / 清理 | | ---- | ----------- | ----- | ------------- | | A——AI 模式（agents 首选） | Agent 会话，多次调用 aliyun | 先运行 aliyun configure ai-mode enable，然后运行 aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance" | [必须] 每次退出（成功、失败、错误、取消、会话结束）时，均须在最终响应前运行 aliyun configure ai-mode disable。启用 AI 模式期间，不得通过 export ALIBABA_CLOUD_USER_AGENT 导出相同的值。 | | B——环境变量或单次命令 | 一次性命令、不使用 configure 的脚本，或未启用 AI 模式 | 在会话中运行 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，以免其他 skills 被错误归因。内联前缀无需执行 unset。对于同一个 skill 字符串，路径 B 不得启用 AI 模式。 |

路径 A——启动（在首次执行会访问 API 的 aliyun 命令之前；如有需要，可先运行不进行云端调用的本地 aliyun configure）：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance"

路径 A——[必须] 每次退出时禁用（skill 停止后，AI 模式不得保持启用）：

aliyun configure ai-mode disable

路径 B——示例（每个工作流只能使用一种载体：export、内联环境变量或根级 --user-agent；不得叠加同一令牌，也不得与路径 A 混用）：

export ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance
# … aliyun … calls … then: unset ALIBABA_CLOUD_USER_AGENT

ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance aliyun ecs DescribeRegions

根级 --user-agent 也属于路径 B 的用法，对于同一令牌，不得与路径 A 结合使用。非 agent复制粘贴：路径 B 通常已足够；agent 会话：使用路径 A，并在退出时禁用。以下示例仅使用路径 A 或 B，绝不同时使用二者。

预检查：阿里云 CLI 必须 >= 3.3.3——运行 aliyun version。如果版本过低：运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash，或参阅 references/installation-guide.md。

预检查：必须更新阿里云 CLI 插件——[必须] 运行 aliyun configure set --auto-plugin-install true；[必须] 运行 aliyun plugin update。

CLI 版本里程碑（agents 和用户）

| 起始版本 | 新增功能 | | ------------- | -------------- | | >= 3.3.3 | 此 skill 中产品插件和流程所需的基准版本（请参阅上述预检查）。 | | >= 3.3.5 | aliyun upgrade——当该子命令存在时，可通过二进制文件本身更新 CLI。CLI 版本足够新后，例行升级应优先使用该命令，而不是重新运行安装脚本。 | | >= 3.3.8 | aliyun plugin show --name <plugin>——查看已安装插件的详细信息（版本、产品代码、说明，以及 API 版本，如有）。在较旧的 CLIs 上，仅使用 aliyun plugin list 和产品的 --help。 |

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 代替 curl 安装程序（首次安装或 upgrade 不可用时，安装程序仍然适用）：

aliyun version   # confirm >= 3.3.5 before relying on upgrade
aliyun upgrade

OAuth（浏览器登录）

当同一台机器上可以打开浏览器时（例如带有 GUI 的本地桌面），相比存储 AccessKey 对，优先使用 OAuth：凭证不会以明文 AK/SecretKey 的形式保存在配置中，并且登录可以使用 SSO。要求阿里云 CLI 版本为 3.0.299 或更高。不适用于无头环境（例如没有本地浏览器、仅支持 SSH 的服务器）。

以交互方式运行：

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

完整设置（管理员同意、RAM 身份分配以及 CN 与 INTL 站点的选择）详见为阿里云 CLI 配置 OAuth 身份验证和 ./references/installation-guide.md。

# Credentials via environment variables (automation, CI/CD, headless, or when OAuth is not available)
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>

# API calls + this skill: use path A (ai-mode) OR path B (ALIBABA_CLOUD_USER_AGENT) — not both — see "Agent execution: AI-mode and User-Agent (this skill)"

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

阿里云 CLI 3.3.3+ 支持所有已发布的阿里云产品插件。较新的命令（aliyun upgrade 从 3.3.5 起提供，aliyun plugin show 从 3.3.8 起提供）已汇总在本说明开头附近的 CLI 版本里程碑下。

身份验证模式（环境变量）

对于使用显式密钥或令牌的模式（非 OAuth），请选择适合部署场景的模式。设置后，这些环境变量会覆盖 ~/.aliyun/config.json 中的所有值。

| 模式 | 适用场景 | 环境变量 | | ---- | ----------- | --------------------- | | 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 相同的变量（AK + 密钥 + ALIBABA_CLOUD_SECURITY_TOKEN） |

多个账户或环境

每个 shell 会话、CI 作业或密钥存储应分别使用独立的 export 块（ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET / ALIBABA_CLOUD_REGION_ID 的值不同）。对于使用配置文件中命名配置的工作流，请参见 ./references/installation-guide.md。

2. 构建任何命令前先查看 --help

内置命令在不同 APIs 中的参数命名并不一致——有些使用 PascalCase， 有些使用 camelCase，且无法预知确切名称。猜测参数名称经常 会导致错误，需要多次重试。先运行 --help 只需几秒：

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

帮助输出是权威依据。插件帮助尤其详尽——其中包含每个参数的类型 信息、结构字段、格式提示和约束。

安装插件后，aliyun <product> --help 会自动显示插件帮助。要改为查看 旧版内置（OpenAPI 风格）帮助：

ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true aliyun ecs --help

3. 确保服务插件可用

每个阿里云产品都有一个 CLI 插件。插件提供命名一致的 kebab-case 命令， 并配有全面的帮助信息；而旧版内置系统命名不一致，且仅提供少量 帮助信息。如果知道要使用哪个产品，请直接安装该插件——plugin install 具有 幂等性（即使已安装也可安全运行）：

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         # Aliyun CLI >= 3.3.8 — details for one installed plugin

plugin show 要求 阿里云 CLI >= 3.3.8，且仅适用于已安装的插件（使用 plugin list-remote / plugin search 查看插件目录）。在较旧版本中，请省略 plugin show，改用 plugin list 和 aliyun <product> --help。

插件名称既可使用短格式（ecs），也可使用完整格式（aliyun-cli-ecs），且不区分大小写。

插件生命周期：

aliyun plugin update --name ecs              # Update a plugin
aliyun plugin uninstall --name ecs           # Remove a plugin

4. 优先使用插件命令而非内置命令

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

• 全小写子命令 → 路由到插件（CLI 原生风格）
• 包含大写字母 → 路由到内置系统（OpenAPI 风格）

插件命令的子命令和参数均采用一致的 kebab-case 命名，因此 易于预测。内置命令使用 PascalCase 子命令，其参数 命名方式混杂且不一致，并且会因 API 而异——你必须为每条命令查看 --help，才能知道确切的名称。

# 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

混用这两种风格会导致静默失败——CLI 会根据子命令 的大小写将命令路由到不同的后端。一个 kebab-case 子命令如果使用 PascalCase 参数，就会被发送到插件系统， 而该系统无法识别 PascalCase 参数名。

产品代码始终不区分大小写（ecs、Ecs、ECS 均可用）。

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

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

CLI 插件系统会保留某些全局参数供自身使用：

• --region-id / --region——控制将请求发送到哪个 API 端点（例如

ecs.cn-hangzhou.aliyuncs.com）。这属于路由问题，而非业务字段。

• 其他全局参数还包括 --profile、--api-version、--output 等。

许多 APIs 还会在 API 规范中定义自己的 RegionId 或 Region 参数——这些是 业务参数，其含义因 API 而异（例如“要在其中创建此资源的地域”）。 全局 --region-id 与 API 的 RegionId 用途不同，但二者会 在命令行上发生冲突。

插件系统会在代码生成过程中自动解决此问题：

1. --biz- 前缀（默认）：API 参数 RegionId 会变为 --biz-region-id
2. --<product>- 前缀（回退）：如果 --biz-region-id 已被另一个

参数占用，插件会回退到 --<product>-region-id（例如 --ecs-region-id）

这意味着在插件命令中，--region-id 始终是全局端点选择器，而 业务地域参数是 --biz-region-id（或 --<product>-region-id）。在本想设置业务参数时使用 --region-id， 会静默更改端点，却不会设置预期字段。

始终查看 --help 以确认实际参数名称——它是判断 给定命令使用 --biz-region-id、--<product>-region-id 还是其他名称的权威依据。

6. 使用结构化参数语法

插件支持由框架自动序列化的结构化输入，从而避免 使用容易出错的旧版 --Tag.N.Key / --Param.N=value 语法。

基本类型和列表：

--instance-id i-abc123                                  # single value
--security-group-ids sg-001 sg-002 sg-003               # space-separated list
--instance-id i-abc --instance-id i-def                 # repeated param (also valid)

键值对象和可重复结构：

--tag Key=env Value=prod --tag Key=app Value=web        # repeatable key-value
--capacity-options OnDemandBaseCapacity=12 CompensateWithOnDemand=true  # object
--data-disk '{"DiskName":"d1","Size":100}'              # complex structure (JSON)

查看每个命令的 --help——其中会显示确切类型、结构字段，以及 参数是否可重复指定。

7. OSS 使用自定义命令

与其他产品不同，OSS 采用手工编写的实现，并使用自定义命令语法。 API 风格的命令（例如 PutBucket 或 GetObject）在 OSS 中不存在——使用这些命令会 静默失败或产生令人困惑的错误。务必先查看帮助：

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

以下各行仅为语法示例（使用 <your-*> 占位符）。不得原样运行这些命令——执行前，请替换为真实的路径、存储桶名称和文件名。

aliyun oss cp <your-file-name>.txt oss://<your-bucket-name>/      # Upload
aliyun oss mb oss://<your-bucket-name>              # Create bucket
aliyun ossutil sync ./<your-folder-name>/ oss://<your-bucket-name>/ # Sync directory

8. 筛选并格式化输出

使用 --cli-query（JMESPath）从 API 响应中提取特定字段，并使用 --output 控制格式。这样可避免通过外部工具以管道方式处理大块 JSON 数据：

# JMESPath filter: only running instances, selected fields
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 json              # default
aliyun ecs describe-instances --biz-region-id cn-hangzhou --output table             # human-readable table
aliyun ecs describe-instances --biz-region-id cn-hangzhou --output cols=InstanceId,InstanceName,Status rows="Instances.Instance[]"  # custom columns

9. 分页

许多列表命令会返回分页结果。使用 --page-number 和 --page-size 进行控制：

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

如需自动获取所有页面而无需手动循环，请使用 --pager：

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

path 参数指定要合并的分页数据位于哪个 JSON 字段中。

10. 等待资源状态

某些命令支持用于自动化的内置等待器——持续轮询，直至资源达到所需状态：

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

11. 调试

排查命令失败问题时，以下标志可揭示底层情况，包括完整的 HTTP 请求/响应和参数验证详情：

• --log-level debug——详细的请求/响应日志（显示端点、序列化后的参数和响应）
• --cli-dry-run——不执行命令，仅进行验证（检查参数解析）
• ALIBABA_CLOUD_CLI_LOG_CONFIG=debug——用于全局设置日志级别的环境变量

对于 403、禁止访问、NoPermission 或其他 RAM 类拒绝错误，凭据对应的身份缺少执行底层 API 操作所需的权限。有关此 skill 的 required_permissions 表、按需授权以及如何缩小权限范围，请参阅 ./references/ram-policies.md。

12. 多版本 API 支持

某些产品（例如 ESS、SLB）提供多个 API 版本，各版本具有不同的命令集和 功能。使用错误版本可能导致参数缺失、触发已弃用的行为，或 可用命令完全不同。并非所有产品都有多个版本——如果 list-api-versions 返回错误，则该产品为单版本，无需执行任何操作。

查看可用版本

aliyun <product> list-api-versions

示例（ESS；* = 默认）：

* 2014-08-28 (default)
  2022-02-22

每个版本可能会提供不同的命令或参数名称。

为每条命令指定版本

aliyun ess describe-scaling-groups --api-version 2022-02-22 --biz-region-id cn-hangzhou

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

为避免每次调用都传入 --api-version，请为产品设置默认版本：

export ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22
export ALIBABA_CLOUD_SLB_API_VERSION=2014-05-15

格式为 ALIBABA_CLOUD_<PRODUCT_CODE>_API_VERSION（产品代码使用大写）。 这在脚本或 CI/CD 中尤其有用，可确保多个命令的版本行为 保持一致。

查看特定版本的命令

不同的 API 版本可能具有不同的命令集。要查看可用命令：

aliyun ess --api-version 2022-02-22    # List commands in this version
aliyun ess <cmd> --api-version 2022-02-22 --help   # Help for a specific command in this version

何时需要指定版本

• 默认版本——除非需要较新功能，否则已足够。
• --help——缺失的参数可能只存在于其他 API 版本中。
• 脚本 / CI——固定使用 ALIBABA_CLOUD_<PRODUCT>_API_VERSION 以确保可复现性。

全局标志参考

以下标志可用于所有插件命令：

| 标志 | 用途 | | ---- | ------- | | --region <region> | API 端点区域（全局参数，并非业务区域） | | --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 | 自动合并可分页 APIs 的所有页面 |

常见工作流

ECS 实例

aliyun plugin list | grep ecs
# If missing: aliyun plugin install --names ecs

aliyun ecs describe-instances --biz-region-id cn-hangzhou

以下 create-instance 示例会创建计费资源（示例中使用固定的镜像 ID、实例规格和磁盘）。不得原样运行——执行前，请根据您的账号和策略调整区域、镜像、规格、磁盘、网络和标签。

aliyun ecs create-instance \
  --biz-region-id cn-hangzhou \
  --instance-type ecs.g7.large \
  --image-id ubuntu_20_04_arm64_20G_alibase_20250625.vhd \
  --data-disk Category=cloud_essd Size=100 \
  --tag Key=env Value=prod --tag Key=app Value=web

函数计算（ROA 请求体展开）

aliyun plugin list | grep fc
# If missing: aliyun plugin install --names fc

以下代码块是一个语法示例（<your-function-name> 及其他值仅用于说明）。不得原样运行——请设置真实的函数名称、运行时、处理程序、内存和超时时间，并添加您的环境所需的任何 VPC 或服务角色设置。插件命令会将 ROA 请求体字段展开为各个参数（无需 --body JSON）。

aliyun fc create-function \
  --function-name <your-function-name> \
  --runtime python3.9 \
  --handler index.handler \
  --memory-size 512 \
  --timeout 60 \
  --description "Process uploaded images"

多版本 API（ESS）

# Check available versions
aliyun ess list-api-versions

# Use the latest version for new features
export ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22
aliyun ess describe-scaling-groups --biz-region-id cn-hangzhou

# Or specify per command without env var
aliyun ess describe-scaling-groups --api-version 2022-02-22 --biz-region-id cn-hangzhou

响应格式

提供 CLI 命令时：

1. 说明命令的作用以及使用特定参数的原因
2. 显示包含所有必需参数的完整命令
3. 明确说明不易理解的值——尤其是带 --biz- 前缀的参数及其原因
4. 用户进行故障排查时，建议使用 --log-level debug
5. 对于 API 归因，应选择以下任一种方式：AI-mode + set-user-agent，或环境变量/内联形式的 ALIBABA_CLOUD_USER_AGENT；对于同一个 skill token，禁止同时使用两者；agents 应在每次退出时禁用 AI-mode，或在 export 后执行 unset（请参阅 Agent 执行：AI-mode 和 User-Agent（此 skill））

参考资料

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