Alibabacloud Cli Guidance

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

Agent execution: AI-mode and User-Agent (this skill)

Skill identifier (same string whichever path you use): AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance

Use exactly one way to attach this skill to requests. Do not combine AI-mode (configure ai-mode + set-user-agent) with ALIBABA_CLOUD_USER_AGENT or a per-command env prefix for the same skill token — the CLI stacks those sources, and User-Agent / attribution will duplicate (bad for telemetry).

Path A — start (before the first aliyun that hits the API; local aliyun configure without cloud calls may run first if needed):

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

Path A — [MUST] disable at every exit (AI-mode must not remain on after the skill stops):

aliyun configure ai-mode disable

Path B — examples (one carrier per workflow: export, inline env, or root --user-agent; never stack the same token or mix with path 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

Root `--user-agent` is path B semantics too — do not combine with path A for the same token. Non-agent copy-paste: path B is often enough; agent sessions: path A + disable on exit. Examples below use path A or B only, never both.

Pre-check: Aliyun CLI >= 3.3.3 required — Run aliyun version. If too low: curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash or see references/installation-guide.md.

Pre-check: Aliyun CLI plugin update required — [MUST] aliyun configure set --auto-plugin-install true; [MUST] aliyun plugin update.

CLI version milestones (agents and users)

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:

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

After the CLI is at 3.3.5 or newer, routine self-updates can use `aliyun upgrade` instead of the curl installer (the installer remains appropriate for first-time install or when upgrade is not available):

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

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:

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

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.

# 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+ supports all published Alibaba Cloud product plugins. Newer commands (aliyun upgrade from 3.3.5, aliyun plugin show from 3.3.8) are summarized under CLI version milestones near the top of these instructions.

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.

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:

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:

ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true aliyun ecs --help

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

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:

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 requires Aliyun CLI >= 3.3.8 and only works for installed plugins (use plugin list-remote / plugin search to inspect the catalog). On older versions, omit plugin show and rely on plugin list plus aliyun <product> --help.

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

Plugin lifecycle:

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

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.

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

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. `--biz-` prefix (default): the API parameter RegionId becomes --biz-region-id 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:

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

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

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:

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.

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

# 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. Pagination

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

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:

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.

10. Wait for resource state

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

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

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

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

aliyun <product> list-api-versions

Example (ESS; * = default):

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

Each version may expose different commands or parameter names.

Specify version per command

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:

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.

View commands for a specific version

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

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

When to specify version

• Default — enough unless you need newer features.
• `--help` — missing parameter may exist only in another API version.
• Scripts / CI — pin ALIBABA_CLOUD_<PRODUCT>_API_VERSION for reproducibility.

Global Flags Reference

These flags are available on all plugin commands:

Common Workflows

ECS Instances

aliyun plugin list | grep ecs
# If missing: 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.

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)

aliyun plugin list | grep fc
# If missing: 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).

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)

# 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

Response Format

When providing CLI commands:

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 attribution, use either AI-mode + set-user-agent or env/inline ALIBABA_CLOUD_USER_AGENT, never both for the same skill token; agents should disable AI-mode on every exit or unset after export (see Agent execution: AI-mode and User-Agent (this skill))

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

Command Syntax Guide

Supplementary reference for the Aliyun CLI plugin system. For core usage instructions, see SKILL.md (the primary document).

Basic Command Structure

aliyun <product> <command> [--parameter value] [--global-flag value]

• <product>: Plugin name (ecs, fc, rds, oss, sls, etc.)
• <command>: Operation in kebab-case (describe-instances, create-function)
• --parameter: Command-specific parameters in kebab-case
• --global-flag: Global flags like --region-id, --output, --log-level

Parameter Types, Output Filtering, Global Flags, Pagination, Waiters

See SKILL.md §6 (structured parameters), §8 (filter and format output), §9 (pagination), §10 (waiters), and the Global Flags Reference table.

JSON Parameters (supplementary)

For very complex structures where structured syntax is insufficient, raw JSON is supported:

aliyun fc create-function \
  --function-name test \
  --code '{"zipFile":"base64encoded..."}'

Help System

aliyun ecs --help                              # Product-level: list all subcommands
aliyun ecs describe-instances --help           # Command-level: parameters, types, structure
aliyun ecs --help | grep "Available Commands"  # Quick command listing

When a plugin is installed, aliyun <product> --help shows plugin help automatically. See SKILL.md §2 for details on ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP.

Error Handling

Common Error Messages

1. Plugin not found

   Error: plugin 'xxx' not found
   Solution: aliyun plugin install --names xxx

2. Missing required parameter

   Error: required parameter '--instance-id' not provided
   Solution: Add the required parameter. Check --help for required params.

3. Invalid parameter value

   Error: invalid value for '--instance-type'
   Solution: Check valid values with --help

4. API version not supported

   Error: unsupported API version
   Solution: aliyun <product> list-api-versions

5. Authentication error

   Error: InvalidAccessKeyId.NotFound
   Solution: aliyun configure set --access-key-id <new-key> --access-key-secret <new-secret>

6. Signature mismatch

   Error: SignatureDoesNotMatch
   Solution: Verify access key secret. Check for extra whitespace in credentials.

Debugging failed commands

Always add --log-level debug to see the full request/response cycle:

aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --log-level debug

This reveals: API endpoint, serialized parameters, HTTP status, and response body.

Global Flags Reference

Supplementary reference for CLI global flags. For commonly used flags, see SKILL.md (Global Flags Reference table, §8 output filtering, §11 debugging).

This document covers hidden/advanced flags and details not in SKILL.md.

Hidden Global Flags

These flags are available but not shown in --help:

--waiter (advanced syntax)

SKILL.md §10 shows basic waiter usage. Full syntax with timeout and interval:

aliyun ecs describe-instances \
  --instance-id i-xxx \
  --waiter expr='Instances.Instance[0].Status' to=Running timeout=180 interval=5

• expr: JMESPath expression to evaluate on the response
• to: Target value to match
• timeout: Maximum wait in seconds (default varies)
• interval: Poll interval in seconds (default varies)

--header

Add custom HTTP headers (repeatable):

aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --header X-Custom-Header=value \
  --header X-Another-Header=value2

--body / --body-file

Provide raw HTTP request body directly or from file:

aliyun fc invoke-function \
  --function-name test \
  --body '{"key":"value"}'

aliyun fc create-function \
  --function-name test \
  --body-file ./function-config.json

--secure / --insecure

Force HTTPS or HTTP protocol:

aliyun ecs describe-instances --secure      # Force HTTPS
aliyun ecs describe-instances --insecure    # Force HTTP (not recommended)

--no-stream

For SSE (Server-Sent Events) APIs: aggregate all events before displaying instead of streaming them incrementally:

aliyun <product> <sse-command> --no-stream

--cli-dry-run Example Output

When using --cli-dry-run, the CLI prints what would be sent without calling the API:

[DRY-RUN] API call would be made with the following details:
  Endpoint: https://ecs.cn-hangzhou.aliyuncs.com
  Method: POST
  Headers:
    Content-Type: application/x-www-form-urlencoded
    x-acs-action: CreateInstance
  Parameters:
    RegionId=cn-hangzhou
    InstanceType=ecs.g6.large
    ImageId=ubuntu_20_04_x64

--output rows= Parameter

Use rows= with cols= to specify the JSON path for row data:

aliyun ecs describe-instances \
  --output cols=InstanceId,Status rows='Instances.Instance[]'

Flag Priority

When the same setting is configured in multiple places:

1. Command-line flag (highest) 2. Environment variable 3. Config file (~/.aliyun/config.json) 4. Default value (lowest)

export ALIBABA_CLOUD_REGION_ID=cn-beijing
aliyun ecs describe-instances --biz-region-id cn-hangzhou
# Uses cn-hangzhou (command-line wins)

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.3+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.

Installation

macOS / Linux (Recommended)

One command to install or update — works on both macOS and Linux, auto-detects architecture:

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

After installation, verify:

aliyun version   # should be >= 3.3.3

macOS — Homebrew (Alternative)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

Linux — Manual Binary (Alternative)

Use these only if the setup script above is not suitable.

x86_64

wget --connect-timeout=10 --read-timeout=120 --tries=3 -qO- https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz | tar xz
sudo mv aliyun /usr/local/bin/

ARM64

wget --connect-timeout=10 --read-timeout=120 --tries=3 -qO- https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz | tar xz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

Where to Get Access Keys

1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

OAuth (browser login) — If the environment can open a web browser (for example a local desktop with a GUI), prefer OAuth over storing AccessKey pairs in configuration: credentials are not kept as plaintext AK/SecretKey. Requires Alibaba Cloud CLI 3.0.299 or later and is not suitable for headless servers (for example SSH-only Linux without a browser on the same machine).

Run interactively:

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

Full setup (administrator consent, RAM assignments, site CN vs INTL) is covered in the official guide: Configure OAuth authentication for Alibaba Cloud CLI.

---

The sections below describe six authentication modes that are typically driven with non-interactive flags (scripts, CI/CD, automation). Use these when OAuth is not available or when you must supply explicit keys or tokens.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "<your-access-key-id>",
      "access_key_secret": "<your-access-key-secret>",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --sts-token <your-sts-token> \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --ram-role-arn <your-ram-role-arn> \
  --role-session-name <your-role-session-name> \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name <your-ecs-ram-role-name> \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key <path-to-your-private-key.pem> \
  --key-pair-name <your-key-pair-name> \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name <your-ecs-ram-role-name> \
  --ram-role-arn <your-ram-role-arn> \
  --role-session-name <your-role-session-name> \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file

Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>
export ALIBABA_CLOUD_SECURITY_TOKEN=<your-sts-token>
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id <your-first-access-key-id> \
  --access-key-secret <your-first-access-key-secret> \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id <your-second-access-key-id> \
  --access-key-secret <your-second-access-key-secret> \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure switch --profile projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins):

1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level debug

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

❌ Don't: Use Aliyun root account credentials ✅ Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id <your-access-key-id> --access-key-secret <your-access-key-secret>
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id <your-access-key-id> --access-key-secret <your-access-key-secret> \
  --sts-token <your-sts-token> --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name <your-ecs-ram-role-name> --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level debug

# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired

# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id <your-access-key-id> --access-key-secret <your-access-key-secret> \
  --sts-token <your-sts-token> --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions

# Update default region
aliyun configure set --region cn-shanghai

Advanced Configuration

Timeout Settings

# Connection timeout
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.3+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak

RAM policies and the Aliyun CLI

Every successful aliyun API call is authorized as your RAM user, RAM role, or STS session. The CLI does not bypass RAM: if an action is denied in the console, it is denied on the command line with the same identity.

Use this note when choosing policies, interpreting errors, or guiding users who automate with the CLI.

required_permissions

RAM permissions for API operations illustrated in SKILL.md. Use the table format below: one row per operation, `Permission Required` is exactly one product:Action — do not put multiple Actions in a single cell or on one table row.

These entries are not exhaustive for every CLI workflow. For commands not covered here, resolve Actions with --log-level debug and product OpenAPI / RAM docs, and authorize on demand.

Administrators typically use a RAM-managed system policy (for example AliyunRAMFullAccess) only for the consenting principal, then grant least privilege to CLI users who sign in via OAuth.

`aliyun ess list-api-versions`: implementation depend on CLI/plugin version and does not map to a single documented ess:* Action.

Local-only behavior (aliyun plugin list for installed plugins, aliyun <product> --help) usually does not call your account’s RAM-protected APIs; plugin install / plugin list-remote need outbound network to Aliyun but often no RAM for your resources.

Start from least privilege

1. Prefer read-only system policies or custom statements that only allow the Describe* / List* / Get* Actions you need. 2. Grant write Actions only for workflows that create, change, or delete resources. 3. Prefer custom policies scoped to specific resources or Actions when a system FullAccess policy is too broad.

Relate policies to CLI operations

• Product plugins (for example aliyun ecs, aliyun vpc) map to that product’s APIs. The RAM Action must match the underlying API (see each product’s OpenAPI and RAM authorization topic).
• Cross-product automation may require multiple Actions — authorize each separately (one `Permission Required` per row in this file’s table; never combine multiple Actions in one cell).

When an error names a missing Action, add a policy statement that allows that product:Action (one Action per array element in JSON policy Action, matching one row here).

Common error signals

Symptoms that usually mean a RAM/policy issue (not a wrong parameter):

• HTTP 403 or messages containing Forbidden, NoPermission, not authorized, Action denied
• Error codes such as Forbidden.RAM, NoPermission, or explicit ACS:CheckSecurity / missing action in the error body

Use --log-level debug on the CLI to see the API and error payload. Then fix the identity’s policies (user or role) in RAM, or ask an administrator to attach policies.

Authoritative policy syntax, condition keys, and the full API-to-Action mapping are maintained by Alibaba Cloud documentation and the RAM console.