alibabacloud-cli-guidance

Aliyun CLI 专家

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

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

说明

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

技能标识符（无论使用哪种路径，字符串都相同）：AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance

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

路径	使用场景	开始	结束 / 清理
A — AI 模式（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 模式开启时，不要将 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，避免错误归因到其他技能。行内前缀无需取消设置。对于同一个技能字符串，不要在路径 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 — 每次退出时都必须禁用（技能停止后，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，不会同时使用两者。

预检查：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 版本里程碑（Agent 和用户）

起始版本	可获得的功能
>= 3.3.3	此技能所用产品插件和工作流的基准版本（参见上述预检查）。
>= 3.3.5	aliyun upgrade — 当存在此子命令时，可直接通过 CLI 二进制文件更新 CLI。CLI 达到此版本后，日常升级优先使用此命令，而不是重新运行安装脚本。
>= 3.3.8	aliyun plugin show --name <plugin> — 查看已安装插件的详细信息（版本、产品代码、说明，以及可用时的 API 版本）。对于较旧的 CLI，只能使用 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（浏览器登录）

当可以在同一台机器上打开浏览器时（例如带图形界面的本地桌面），优先选择 OAuth，而不是存储 AccessKey 密钥对：凭证不会以明文 AK/SecretKey 的形式保存在配置中，并且登录时可以使用 SSO。需要 Alibaba Cloud CLI 3.0.299 或更高版本。不适用于无头环境（例如只能通过 SSH 访问且没有本地浏览器的服务器）。

交互式运行：

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

完整设置（管理员授权、RAM 身份分配、CN 与 INTL 站点）请参阅 为 Alibaba Cloud 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

Aliyun CLI 3.3.3+ 支持所有已发布的 Alibaba Cloud 产品插件。较新的命令（从 3.3.5 起支持 aliyun upgrade，从 3.3.8 起支持 aliyun plugin show）已汇总在本说明开头附近的 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 + secret + 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

内置命令在不同 API 中的参数命名不一致——有些使用 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. 确保服务插件可用

Alibaba Cloud 的每个产品都有一个 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 需要 Aliyun 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	展开为单独参数	单个 --body JSON
Header 参数	在帮助中可见，可直接使用	隐藏，仅可手动使用 --header
帮助	全面，包含结构信息	基本

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

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

• --region-id / --region — 控制请求发送到哪个 API 端点（例如 ecs.cn-hangzhou.aliyuncs.com）。这是路由设置，不是业务字段。
• 其他全局参数包括 --profile、--api-version、--output 等。

许多 API 也会在 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 使用手写实现和自定义命令语法。OSS 不支持 PutBucket 或 GetObject 之类的 API 风格命令——使用这些命令会悄然失败或产生令人困惑的错误。务必先查看帮助：

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、Forbidden、NoPermission 或其他 RAM 风格的拒绝，凭证对应的身份缺少底层 API 操作所需的权限。请参阅 ./references/ram-policies.md，了解此技能的 required_permissions 表、按需授权以及如何缩小权限范围。

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	自动合并可分页 API 的所有页面

常见工作流

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

响应格式

提供命令行命令时：

1. 说明命令的作用，以及使用特定参数的原因
2. 展示包含所有必需参数的完整命令
3. 指出不明显的值，尤其是 --biz- 前缀参数及其用途
4. 如果用户正在排查问题，建议使用 --log-level debug
5. 对于 API 归因，同一技能令牌只能使用 AI-mode + set-user-agent，或环境变量/行内 ALIBABA_CLOUD_USER_AGENT，不能同时使用这两种方式；Agent 应在每次退出时关闭 AI-mode，或在 export 后执行 unset（参见 Agent 执行：AI-mode 和 User-Agent（此技能））

参考资料

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