Aliyun CLI Expert

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.

Instructions

User-Agent (this skill)

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

CODEBLOCK0

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.

1. Install and configure the 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:

CODEBLOCK1

OAuth (browser login)

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:

CODEBLOCK2

Full setup (administrator consent, RAM identity assignments, CN vs INTL site) is documented in Configure OAuth authentication for Alibaba Cloud CLI and ./references/installation-guide.md.

CODEBLOCK3

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

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	INLINECODE15, ALIBABA_CLOUD_ACCESS_KEY_SECRET, INLINECODE17
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) |

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.

2. Consult --help before constructing any command

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:

CODEBLOCK4

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:

CODEBLOCK5

3. Ensure service plugins are available

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

CODEBLOCK6

To discover or verify plugins:

CODEBLOCK7

Plugin names accept both short form (ecs) and full form (aliyun-cli-ecs), case-insensitive.

Plugin lifecycle:

CODEBLOCK8

4. Prefer plugin commands over built-in commands

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.

CODEBLOCK9

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

5. Understand global vs business parameter naming

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

1. 1. --biz- prefix (default): the API parameter RegionId becomes INLINECODE51
2. --<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.

6. Use structured parameter syntax

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:

CODEBLOCK10

Key-value objects and repeatable structures:

CODEBLOCK11

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

7. OSS uses custom commands

Unlike other products, OSS has a hand-written implementation with custom command syntax.
API-style commands like PutBucket or GetObject do not exist for OSS — using them will fail
silently or produce confusing errors. Always check help first:

CODEBLOCK12

The lines below are syntax examples only (<your-*> placeholders). Do not run them verbatim — substitute real paths, bucket names, and file names before executing.

CODEBLOCK13

8. Filter and format output

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:

CODEBLOCK14

9. Pagination

Many list commands return paginated results. Use --page-number and --page-size to control:

CODEBLOCK15

To fetch all pages automatically without manual loops, use --pager:

CODEBLOCK16

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

10. Wait for resource state

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

CODEBLOCK17

11. Debugging

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)
• INLINECODE76 — validate command without executing (checks parameter parsing)
• INLINECODE77 — 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.

12. Multi-version API support

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.

Discover versions

CODEBLOCK18

Example output (ESS):

CODEBLOCK19

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

Specify version per command

CODEBLOCK20

Set a default version via environment variable

To avoid passing --api-version on every call, set the default for a product:

CODEBLOCK21

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.

View commands for a specific version

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

CODEBLOCK22

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

Global Flags Reference

These flags are available on all plugin commands:

Flag	Purpose
INLINECODE85	API endpoint region (global, not business region)
INLINECODE86

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 |

Common Workflows

ECS Instances

CODEBLOCK23

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.

CODEBLOCK24

Function Compute (ROA Body Expansion)

CODEBLOCK25

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

CODEBLOCK26

Multi-Version API (ESS)

CODEBLOCK27

Response Format

When providing CLI commands:

1. 1. Explain what the command does and why specific parameters are used
2. Show the complete command with all required parameters
3. Call out non-obvious values — especially --biz- prefixed parameters and their reason
4. Suggest --log-level debug when the user is troubleshooting
5. 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))

References

• - ./references/installation-guide.md — Installation, configuration modes, credential setup
• INLINECODE104 — Complete command syntax guide
• INLINECODE105 — Global flags reference
• INLINECODE106 — On-demand RAM, least privilege, common permission errors