alibabacloud-cli-guidance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Aliyun CLI Expert

Aliyun CLI 专家

Guide users to manage Alibaba Cloud resources effectively using the

aliyun

command-line tool.

Required permissions : see

./references/ram-policies.md

(

## required_permissions

). Extend on demand for other CLI commands.

指导用户使用

aliyun

命令行工具高效管理阿里云资源。

所需权限：参见

./references/ram-policies.md

（

## required_permissions

部分），其他CLI命令可按需扩展权限。

Instructions

使用说明

User-Agent (this skill)

User-Agent（本技能）

Any

aliyun

invocation that calls Alibaba Cloud APIs while following this skill MUST identify the client with:

bash

export ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills

Use the same shell for subsequent commands, or prefix a single run:

ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills aliyun ...

. Omit this only for steps that do not call cloud APIs (for example local

aliyun configure

browser OAuth setup before any API call). When you give the user copy-paste blocks, include this

export

once at the top of the block (or the inline prefix on each

aliyun

line).

Examples below assume

ALIBABA_CLOUD_USER_AGENT

is set whenever an

aliyun

command hits the API.

任何遵循本技能调用阿里云API的

aliyun

命令，必须将客户端标识设置为：

bash

export ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills

后续命令需在同一shell中执行，或者单次运行时添加前缀：

ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills aliyun ...

。只有在不调用云API的步骤中可以省略该配置（例如首次API调用前的本地

aliyun configure

浏览器OAuth设置）。当你为用户提供可复制的代码块时，请在代码块顶部一次性添加该

export

语句（或者在每一行

aliyun

命令前添加内联前缀）。下面的示例默认调用API的

aliyun

命令都已设置

ALIBABA_CLOUD_USER_AGENT

。

1. Install and configure the CLI

1. 安装并配置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:

bash

undefined

如果用户尚未安装或配置CLI，引导其完成初始化设置。完整细节参见

./references/installation-guide.md

，快速安装路径：

bash

undefined

Install or update (macOS / Linux — one command)

安装或更新（macOS / Linux 单命令执行）

/bin/bash -c "$(curl -fsSL --connect-timeout 10 --max-time 120 https://aliyuncli.alicdn.com/setup.sh)"

undefined

/bin/bash -c "$(curl -fsSL --connect-timeout 10 --max-time 120 https://aliyuncli.alicdn.com/setup.sh)"

undefined

OAuth (browser login)

OAuth（浏览器登录）

When a browser can be opened on the same machine (for example a local desktop with a GUI), prefer OAuth over storing AccessKey pairs: credentials are not kept as plaintext AK/SecretKey in configuration, and sign-in can use SSO. Requires Alibaba Cloud CLI 3.0.299 or later. Not suitable for headless environments (for example SSH-only servers without a local browser).

Run interactively:

bash

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

Full setup (administrator consent, RAM identity assignments,

CN

INTL

site) is documented in Configure OAuth authentication for Alibaba Cloud CLI and

./references/installation-guide.md

bash

undefined

当操作的设备可以打开浏览器时（例如带GUI的本地桌面设备），优先选择OAuth而非存储AccessKey对：凭证不会以明文AK/SecretKey的形式保存在配置中，且支持SSO登录。该方式要求阿里云CLI版本**≥3.0.299**，不适用于无界面环境（例如没有本地浏览器、仅支持SSH访问的服务器）。

交互式执行命令：

bash

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

完整配置流程（管理员同意、RAM身份分配、

CN

与

INTL

站点选择）可查阅为阿里云CLI配置OAuth认证和

./references/installation-guide.md

文档。

bash

undefined

Credentials via environment variables (automation, CI/CD, headless, or when OAuth is not available)

通过环境变量配置凭证（自动化场景、CI/CD、无界面环境或无法使用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:

临时凭证（StsToken）需额外添加：

export ALIBABA_CLOUD_SECURITY_TOKEN=<sts-token>

Required when using this skill for API calls — see "User-Agent (this skill)" above

使用本技能调用API时必需配置，参见上文「User-Agent（本技能）」部分

export ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills

Verify

验证配置

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


Aliyun CLI 3.3.0+ supports all published Alibaba Cloud product plugins.

aliyun version # 版本应 ≥ 3.3.0 aliyun ecs describe-regions # 测试鉴权是否生效


Aliyun CLI 3.3.0及以上版本支持所有已发布的阿里云产品插件。

Authentication modes (environment variables)

鉴权模式（环境变量）

For modes that use explicit keys or tokens (not OAuth), choose what fits the deployment context. When set, these environment variables override any values in

~/.aliyun/config.json

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	Export the temporary pair from the role session: same variables as StsToken (AK + secret + `ALIBABA_CLOUD_SECURITY_TOKEN` )

对于使用显式密钥或令牌的模式（非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` ）

Multiple accounts or environments

多账号或多环境管理

Use separate

export

blocks per shell session, CI job, or secret store (different

ALIBABA_CLOUD_ACCESS_KEY_ID

ALIBABA_CLOUD_ACCESS_KEY_SECRET

ALIBABA_CLOUD_REGION_ID

values). For profile-based workflows backed by the config file, see

./references/installation-guide.md

可以为每个shell会话、CI任务或密钥存储配置独立的

export

代码块（使用不同的

ALIBABA_CLOUD_ACCESS_KEY_ID

ALIBABA_CLOUD_ACCESS_KEY_SECRET

ALIBABA_CLOUD_REGION_ID

值）。基于配置文件的配置流参见

./references/installation-guide.md

。

2. Consult

--help

before constructing any command

2. 构建命令前先查阅

--help

信息

Built-in commands have inconsistent parameter naming across APIs — some use PascalCase, others camelCase, and the exact names are not predictable. Guessing parameter names frequently leads to errors that require multiple retries. Running

--help

first takes seconds:

bash

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

Help output is the authoritative source. Plugin help is especially rich — it includes type info, structure fields, format hints, and constraints for every parameter.

When a plugin is installed,

aliyun <product> --help

automatically shows plugin help. To view the legacy built-in (OpenAPI-style) help instead:

bash

ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true aliyun ecs --help

内置命令的参数命名在不同API之间没有统一规范，部分使用帕斯卡命名法，部分使用驼峰命名法，无法预测准确名称。猜测参数名称通常会导致错误，需要多次重试，先执行

--help

查询仅需数秒：

bash

aliyun <product> --help                # 查看可用的子命令
aliyun <product> <subcommand> --help   # 获取准确的参数名称、类型、结构说明

帮助文档是最权威的信息来源，插件的帮助信息尤其丰富，包含每个参数的类型信息、结构字段、格式提示和约束条件。

安装插件后，

aliyun <product> --help

会自动展示插件的帮助信息，如果需要查看旧版内置（OpenAPI风格）的帮助信息，可执行：

bash

ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true aliyun ecs --help

3. Ensure service plugins are available

3. 确保已安装对应服务插件

Each Alibaba Cloud product has a CLI plugin. Plugins provide consistent kebab-case commands with comprehensive help, while the legacy built-in system has inconsistent naming and minimal help. If you know which product to use, install the plugin directly —

plugin install

is idempotent (safe to run even if already installed):

bash

aliyun plugin install --names ecs     # Install (short name, case-insensitive)
aliyun plugin install --names ECS VPC RDS   # Multiple at once

To discover or verify plugins:

bash

aliyun plugin list                    # Installed plugins
aliyun plugin list-remote             # All available plugins
aliyun plugin search <keyword>        # Search by keyword

Plugin names accept both short form (

ecs

) and full form (

aliyun-cli-ecs

), case-insensitive.

Plugin lifecycle:

bash

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

每个阿里云产品都有对应的CLI插件，插件提供统一的短横线分隔命名的命令和全面的帮助信息，而旧版内置系统命名不统一、帮助信息极少。如果明确要使用的产品，可直接安装插件，

plugin install

是幂等操作（即使已安装也可安全执行）：

bash

aliyun plugin install --names ecs     # 安装单个插件（短名称，不区分大小写）
aliyun plugin install --names ECS VPC RDS   # 同时安装多个插件

查询或验证插件的命令：

bash

aliyun plugin list                    # 已安装的插件列表
aliyun plugin list-remote             # 所有可用的插件列表
aliyun plugin search <keyword>        # 按关键词搜索插件

插件名称支持短格式（

ecs

）和全格式（

aliyun-cli-ecs

），不区分大小写。

插件生命周期管理命令：

bash

aliyun plugin update --name ecs              # 更新插件
aliyun plugin uninstall --name ecs           # 卸载插件

4. Prefer plugin commands over built-in commands

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

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 commands use consistent kebab-case naming for both subcommands and parameters, making them predictable. Built-in commands use PascalCase subcommands with mixed/inconsistent parameter naming that varies by API — you must check

--help

for every command to know the exact names.

bash

undefined

CLI支持两种命令风格，子命令的大小写决定了使用哪个系统处理：

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

插件命令的子命令和参数都使用统一的短横线分隔命名，可预测性强。内置命令使用帕斯卡命名的子命令，参数命名混乱且不统一，不同API之间存在差异，必须为每个命令查询

--help

才能获取准确名称。

bash

undefined

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


Mixing styles causes silent failures — the CLI routes to different backends based on subcommand
casing. A kebab-case subcommand with PascalCase parameters will be sent to the plugin system,
which doesn't recognize PascalCase parameter names.

Product code is always case-insensitive (`ecs`, `Ecs`, `ECS` all work).

| 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 |

aliyun ecs DescribeInstances --RegionId cn-hangzhou


混合使用两种风格会导致静默失败，CLI会根据子命令的大小写路由到不同的后端。短横线命名的子命令搭配帕斯卡命名的参数会被发送到插件系统，而插件系统无法识别帕斯卡命名的参数。

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

| 对比项 | 插件命令（CLI原生） | 内置命令（OpenAPI） |
| ------ | ------------------- | ------------------ |
| 子命令 | `describe-instances` | `DescribeInstances` |
| 参数 | 短横线分隔命名（统一） | 混合命名（不统一） |
| ROA Body | 展开为独立参数 | 单个`--body`JSON参数 |
| Header参数 | 帮助信息可见，可直接使用 | 隐藏，仅支持手动添加`--header` |
| 帮助信息 | 结构完整、内容全面 | 基础信息 |

5. Understand global vs business parameter naming

5. 区分全局参数和业务参数命名

The CLI plugin system reserves certain global parameters for its own use:

```
--region-id
```
/
```
--region
```
— controls which API endpoint the request is sent to (e.g.
```
ecs.cn-hangzhou.aliyuncs.com
```
). This is a routing concern, not a business field.
Other globals include
```
--profile
```
,
```
--api-version
```
,
```
--output
```
, etc.

Many APIs also define their own

RegionId

Region

parameter in the API spec — these are business parameters with API-specific meaning (e.g. "the region to create this resource in"). The global

--region-id

and the API's

RegionId

serve different purposes, but they would collide on the command line.

The plugin system resolves this automatically during code generation:

--biz-
prefix (default): the API parameter
```
RegionId
```
becomes
```
--biz-region-id
```
--<product>-
prefix (fallback): if
```
--biz-region-id
```
is already taken by another parameter, the plugin falls back to
```
--<product>-region-id
```
(e.g.
```
--ecs-region-id
```
)

This means in plugin commands,

--region-id

is always the global endpoint selector, and the business region is

--biz-region-id

(or

--<product>-region-id

). Using

--region-id

where you meant the business parameter silently changes the endpoint without setting the intended field.

Always check

--help

to see the actual parameter name — it is the authoritative source for whether a given command uses

--biz-region-id

--<product>-region-id

, or something else.

CLI插件系统预留了部分全局参数供自身使用：

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

很多API也会在接口定义中声明自己的

RegionId

或

Region

参数，这些是业务参数，具有API特定的含义（例如「创建资源的所属地域」）。全局

--region-id

和API的

RegionId

用途不同，但在命令行中会产生命名冲突。

插件系统在代码生成阶段会自动解决该冲突：

默认添加
--biz-
前缀：API参数
```
RegionId
```
会变为
```
--biz-region-id
```
兜底添加
--<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. Use structured parameter syntax

6. 使用结构化参数语法

Plugins support structured input that the framework serializes automatically. This avoids the error-prone legacy

--Tag.N.Key

--Param.N=value

syntax.

Primitives and lists:

bash

--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)

Key-value objects and repeatable structures:

bash

--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)

Check

--help

for each command — it shows the exact type, structure fields, and whether a parameter is repeatable.

插件支持结构化输入，框架会自动序列化，避免使用容易出错的旧版

--Tag.N.Key

--Param.N=value

语法。

基础类型和列表：

bash

--instance-id i-abc123                                  # 单个值
--security-group-ids sg-001 sg-002 sg-003               # 空格分隔的列表
--instance-id i-abc --instance-id i-def                 # 重复参数（同样生效）

键值对象和可重复结构：

bash

--tag Key=env Value=prod --tag Key=app Value=web        # 可重复键值对
--capacity-options OnDemandBaseCapacity=12 CompensateWithOnDemand=true  # 对象
--data-disk '{"DiskName":"d1","Size":100}'              # 复杂结构（JSON格式）

请为每个命令查询

--help

，它会展示准确的类型、结构字段，以及参数是否可重复。

7. OSS uses custom commands

7. OSS使用自定义命令

Unlike other products, OSS has a hand-written implementation with custom command syntax. API-style commands like

PutBucket

GetObject

do not exist for OSS — using them will fail silently or produce confusing errors. Always check help first:

bash

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

The lines below are syntax examples only (

<your-*>

placeholders). Do not run them verbatim — substitute real paths, bucket names, and file names before executing.

bash

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

与其他产品不同，OSS使用定制化实现，有专属的命令语法，不存在

PutBucket

或

GetObject

这类API风格的命令，使用这类命令会静默失败或产生难以理解的错误，请始终先查询帮助信息：

bash

aliyun oss --help        # 基础操作（cp、ls、mb、rm等）
aliyun ossutil --help    # 高级工具（sync、stat等）

下面的命令仅为语法示例（

<your-*>

为占位符），不要直接执行，执行前请替换为真实的路径、桶名称和文件名。

bash

aliyun oss cp <your-file-name>.txt oss://<your-bucket-name>/      # 上传文件
aliyun oss mb oss://<your-bucket-name>              # 创建存储桶
aliyun ossutil sync ./<your-folder-name>/ oss://<your-bucket-name>/ # 同步目录

8. Filter and format output

8. 过滤和格式化输出

Use

--cli-query

(JMESPath) to extract specific fields from API responses, and

--output

to control the format. This avoids piping large JSON blobs through external tools:

bash

undefined

使用

--cli-query

（JMESPath）从API响应中提取特定字段，使用

--output

控制输出格式，避免通过外部工具处理大量JSON数据：

bash

undefined

JMESPath filter: only running instances, selected fields

JMESPath过滤器：仅查询运行中实例的指定字段

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

undefined

aliyun ecs describe-instances --biz-region-id cn-hangzhou --output json # 默认格式 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[]" # 自定义列

undefined

9. Pagination

9. 分页

Many list commands return paginated results. Use

--page-number

and

--page-size

to control:

bash

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

To fetch all pages automatically without manual loops, use

--pager

bash

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

The

path

argument specifies which JSON field contains the page data to merge.

很多列表命令返回分页结果，可使用

--page-number

和

--page-size

控制分页：

bash

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

如果需要自动获取所有分页结果无需手动循环，可使用

--pager

：

bash

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

path

参数指定了需要合并的分页数据对应的JSON字段。

10. Wait for resource state

10. 等待资源状态变更

Some commands support built-in waiters for automation — poll until a resource reaches the desired state:

bash

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

部分命令支持内置的等待器，可用于自动化场景，轮询直到资源达到预期状态：

bash

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

11. Debugging

11. 调试

When troubleshooting command failures, these flags reveal what's happening under the hood — the full HTTP request/response and parameter validation details:

```
--log-level debug
```
— detailed request/response logs (shows endpoint, serialized params, response)
```
--cli-dry-run
```
— validate command without executing (checks parameter parsing)
```
ALIBABA_CLOUD_CLI_LOG_CONFIG=debug
```
— environment variable to set log level globally

For 403, Forbidden, NoPermission, or other RAM-style denials, the identity behind the credentials lacks permission for the underlying API action. See

./references/ram-policies.md

for the skill’s

required_permissions

table, on-demand authorization, and how to narrow permissions.

排查命令失败问题时，以下参数可以展示底层执行细节：完整的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. Multi-version API support

12. 多版本API支持

Some products (e.g. ESS, SLB) ship multiple API versions with different command sets and capabilities. Using the wrong version may cause missing parameters, deprecated behavior, or entirely different command availability. Not all products have multiple versions — if

list-api-versions

returns an error, the product is single-version and no action is needed.

部分产品（例如ESS、SLB）提供多个API版本，不同版本的命令集和能力不同。使用错误的版本可能导致参数缺失、行为废弃，甚至完全找不到可用命令。并非所有产品都有多个版本，如果

list-api-versions

返回错误，说明该产品只有单一版本，无需额外操作。

Discover versions

查询版本

bash

aliyun <product> list-api-versions

Example output (ESS):

text

Product: ESS
Supported API versions:
* 2014-08-28 (default)
  2016-07-22
  2022-02-22

The

marks the default version. Each version may expose a different set of commands — newer versions often add commands or change parameter names.

bash

aliyun <product> list-api-versions

示例输出（ESS）：

text

Product: ESS
Supported API versions:
* 2014-08-28 (default)
  2016-07-22
  2022-02-22

标记默认版本，每个版本可能提供不同的命令集，新版本通常会新增命令或修改参数名称。

Specify version per command

单命令指定版本

bash

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

bash

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

Set a default version via environment variable

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

To avoid passing

--api-version

on every call, set the default for a product:

bash

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

The pattern is

ALIBABA_CLOUD_<PRODUCT_CODE>_API_VERSION

(product code in uppercase). This is especially useful in scripts or CI/CD where you want consistent version behavior across multiple commands.

为了避免每次调用都添加

--api-version

，可为产品设置默认版本：

bash

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场景，可保证多个命令使用一致的版本行为。

View commands for a specific version

查看指定版本的命令

Different API versions may have different command sets. To see what's available:

bash

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

不同API版本可能有不同的命令集，查询可用命令的方式：

bash

aliyun ess --api-version 2022-02-22    # 列出该版本的所有命令
aliyun ess <cmd> --api-version 2022-02-22 --help   # 查询该版本下指定命令的帮助信息

When to specify version

何时需要指定版本

Default version works for most cases — only specify when you need features from a newer version
Check
--help
output — if a parameter you expect is missing, it may exist in a different version
Pinning versions in scripts — use the environment variable to ensure reproducible behavior

默认版本适配绝大多数场景 — 仅当需要使用新版本的特性时才需要指定版本
检查
--help
输出 — 如果找不到预期的参数，可能存在于其他版本中
脚本中固定版本 — 使用环境变量保证行为可复现

Global Flags Reference

全局参数参考

These flags are available on all plugin commands:

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

所有插件命令都支持以下参数：

参数	用途
`--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自动合并所有分页结果

Common Workflows

常用工作流

ECS Instances

ECS实例管理

bash

aliyun plugin list | grep ecs

bash

aliyun plugin list | grep ecs

If missing: aliyun plugin install --names ecs

如果未安装：aliyun plugin install --names ecs

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


The `create-instance` example below **provisions billable resources** (fixed image ID, instance type, and disk as illustration). **Do not run it verbatim** — adjust region, image, type, disks, network, and tags for your account and policies before executing.

```bash
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

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


下面的`create-instance`示例**会创建付费资源**（使用固定的镜像ID、实例规格和磁盘作为示例）。**不要直接执行**，执行前请根据你的账号和策略调整地域、镜像、规格、磁盘、网络和标签。

```bash
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

Function Compute (ROA Body Expansion)

函数计算（ROA Body展开）

bash

aliyun plugin list | grep fc

bash

aliyun plugin list | grep fc

If missing: aliyun plugin install --names fc

如果未安装：aliyun plugin install --names fc


The block below is a **syntax example** (`<your-function-name>` and other values are illustrative). **Do not run verbatim** — set the real function name, runtime, handler, memory, timeout, and add any required VPC or service role settings for your environment. Plugin commands expand ROA body fields into individual params (no `--body` JSON needed).

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


下面的代码块是**语法示例**（`<your-function-name>`和其他值仅为示例）。**不要直接执行**，请设置真实的函数名称、运行时、处理程序、内存、超时时间，并根据你的环境添加所需的VPC或服务角色配置。插件命令会将ROA Body字段展开为独立参数（无需使用`--body`JSON参数）。

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

Multi-Version API (ESS)

多版本API（ESS）

bash

undefined

bash

undefined

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

undefined

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

undefined

Response Format

响应格式

When providing CLI commands:

Explain what the command does and why specific parameters are used
Show the complete command with all required parameters
Call out non-obvious values — especially
```
--biz-
```
prefixed parameters and their reason
Suggest
```
--log-level debug
```
when the user is troubleshooting
For API calls, ensure
```
ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills
```
is set in the same shell or inlined before
```
aliyun
```
(see User-Agent (this skill))

提供CLI命令时遵循以下规则：

解释命令的用途，以及使用特定参数的原因
展示包含所有必填参数的完整命令
标注不直观的参数值 — 尤其是
```
--biz-
```
前缀的参数及其使用原因
用户排查问题时建议添加
```
--log-level debug
```
参数
对于API调用，确保在同一shell中设置了
```
ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills
```
，或者在
```
aliyun
```
命令前添加内联前缀（参见**User-Agent（本技能）**部分）

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

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

alibabacloud-cli-guidance

Original

Translation

Aliyun CLI Expert

Aliyun CLI 专家

Instructions

使用说明

User-Agent (this skill)

User-Agent（本技能）

1. Install and configure the CLI

1. 安装并配置CLI

Install or update (macOS / Linux — one command)

安装或更新（macOS / Linux 单命令执行）

OAuth (browser login)

OAuth（浏览器登录）

Credentials via environment variables (automation, CI/CD, headless, or when OAuth is not available)

通过环境变量配置凭证（自动化场景、CI/CD、无界面环境或无法使用OAuth时）

Temporary credentials (StsToken) — add:

临时凭证（StsToken）需额外添加：

export ALIBABA_CLOUD_SECURITY_TOKEN=<sts-token>

export ALIBABA_CLOUD_SECURITY_TOKEN=<sts-token>

Required when using this skill for API calls — see "User-Agent (this skill)" above

使用本技能调用API时必需配置，参见上文「User-Agent（本技能）」部分

Verify

验证配置

Authentication modes (environment variables)

鉴权模式（环境变量）

Multiple accounts or environments

多账号或多环境管理

2. Consult --help before constructing any command

2. 构建命令前先查阅--help信息

3. Ensure service plugins are available

3. 确保已安装对应服务插件

4. Prefer plugin commands over built-in commands

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

Plugin (preferred): consistent kebab-case

插件命令（推荐）：统一的短横线分隔命名

Built-in (fallback): PascalCase subcommand, inconsistent params

内置命令（兜底方案）：帕斯卡命名子命令，参数不统一

5. Understand global vs business parameter naming

5. 区分全局参数和业务参数命名

6. Use structured parameter syntax

6. 使用结构化参数语法

7. OSS uses custom commands

7. OSS使用自定义命令

8. Filter and format output

8. 过滤和格式化输出

JMESPath filter: only running instances, selected fields

JMESPath过滤器：仅查询运行中实例的指定字段

Output formats

输出格式

9. Pagination

9. 分页

10. Wait for resource state

10. 等待资源状态变更

11. Debugging

11. 调试

12. Multi-version API support

12. 多版本API支持

Discover versions

查询版本

Specify version per command

单命令指定版本

Set a default version via environment variable

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

View commands for a specific version

查看指定版本的命令

When to specify version

何时需要指定版本

Global Flags Reference

全局参数参考

Common Workflows

常用工作流

ECS Instances

ECS实例管理

If missing: aliyun plugin install --names ecs

如果未安装：aliyun plugin install --names ecs

Function Compute (ROA Body Expansion)

函数计算（ROA Body展开）

If missing: aliyun plugin install --names fc

2. Consult
`--help`
before constructing any command

2. 构建命令前先查阅
`--help`
信息