Skill: sdk-team/alibabacloud-cli-guidance (version 0.0.2)

--- name: alibabacloud-cli-guidance description: > Guide users to manage Alibaba Cloud resources using the Aliyun CLI command-line tool. Covers CLI installation, credential configuration, plugin management, command construction, and error troubleshooting. Use this skill when the user wants to operate Alibaba Cloud services from the terminal — including ECS (云服务器, cloud servers), Function Compute (函数计算, serverless), RDS (云数据库, databases), OSS (对象存储, object storage), SLS (日志服务, log service), VPC (专有网络, networking), ESS (弹性伸缩, auto scaling), and any other Alibaba Cloud product. Also use when the user mentions "aliyun", "阿里云", "阿里云CLI", "命令行", asks about CLI plugin installation, encounters Aliyun CLI errors (InvalidAccessKeyId, SignatureDoesNotMatch, Throttling), or needs help constructing aliyun commands with correct parameter syntax. license: Apache-2.0 metadata: domain: aliyun-cli owner: sdk-team contact: [REDACTED_SECRET] allowed-tools: Bash, aliyun cli --- # 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): [REDACTED_SECRET] 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 | When to use | Start | End / cleanup | | ---- | ----------- | ----- | ------------- | | **A — AI-mode (preferred for agents)** | Agent session, many `aliyun` calls | `aliyun configure ai-mode enable` then `aliyun configure ai-mode set-user-agent --user-agent [REDACTED_SECRET]` | **[MUST]** `aliyun configure ai-mode disable` before the final response on **every** exit (success, failure, error, cancel, session end). **Do not** `export ALIBABA_CLOUD_USER_AGENT` to the same value while AI-mode is on. | | **B — Environment or one-shot** | One-off commands, scripts without `configure`, or no AI-mode | `export ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance` for the session, **or** prefix each API call: `ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance aliyun ...` | If you used **`export`**, run `unset ALIBABA_CLOUD_USER_AGENT` when done so other skills are not mis-attributed. Inline prefix needs no unset. **Do not** enable AI-mode on path B for the same skill string. | Path A — start (before the first `aliyun` that hits the API; local `aliyun configure` without cloud calls may run first if needed): ```bash aliyun configure ai-mode enable aliyun configure ai-mode set-user-agent --user-agent [REDACTED_SECRET] ``` Path A — **[MUST] disable at every exit** (AI-mode must not remain on after the skill stops): ```bash 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): ```bash export ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance # … aliyun … calls … then: unset ALIBABA_CLOUD_USER_AGENT ``` ```bash 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)** | From version | What you gain | | ------------- | -------------- | | **>= 3.3.3** | Baseline for product plugins and flows in this skill (see pre-checks above). | | **>= 3.3.5** | **`aliyun upgrade`** — update the CLI from the binary itself when the subcommand exists. Prefer it over re-running the install script for routine upgrades once the CLI is new enough. | | **>= 3.3.8** | **`aliyun plugin show --name <plugin>`** — details for an **installed** plugin (version, product code, descriptions, API versions when present). On older CLIs, use `aliyun plugin list` and product `--help` only. | ### 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: ```bash # 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): ```bash 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: ```bash 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](https://www.alibabacloud.com/help/en/doc-detail/2995960.html) and `./references/installation-guide.md`. ```bash # 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`. | 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`) | #### 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: ```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 ``` ### 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): ```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 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: ```bash 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. ```bash # 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 | ### 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:** ```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. ### 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: ```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 ``` ### 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: ```bash # 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: ```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. ### 10. Wait for resource state 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' ``` ### 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) - [REDACTED_SECRET] — 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 ```bash aliyun <product> list-api-versions ``` Example (ESS; `*` = default): ```text * 2014-08-28 (default) 2022-02-22 ``` Each version may expose different commands or parameter names. #### Specify version per command ```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. #### 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 ``` #### 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: | 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 | ## Common Workflows ### ECS Instances ```bash 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. ```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) ```bash 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). ```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) ```bash # 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

path: references/command-syntax.md
content: # Command Syntax Guide

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

## Basic Command Structure

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

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

## Help System

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

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

2. **Missing required parameter**

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

3. **Invalid parameter value**

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

4. **API version not supported**

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

5. **Authentication error**

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

6. **Signature mismatch**

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

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

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


path: references/global-flags.md
content: # 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:

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

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

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

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

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

```text
[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:

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

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


path: references/installation-guide.md
content: # 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:

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

After installation, verify:
```bash
aliyun version   # should be >= 3.3.3
```

### macOS — Homebrew (Alternative)

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

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

```bash
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](https://www.alibabacloud.com/help/en/doc-detail/2995960.html).

---

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.

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

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

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

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

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

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

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

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

```bash
aliyun ecs describe-instances --profile projectA

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

**List and Switch Profiles**

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

```bash
# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions
```

**If successful**, you'll see:
```json
{
  "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

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

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

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

### 3. Rotate Access Keys Regularly

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

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

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

### 6. Never Commit Credentials

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

# Use environment variables in CI/CD instead
```

### 7. Secure Config File

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

## Troubleshooting

### Issue: Command Not Found

```bash
# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH
```

### Issue: Authentication Failed

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

```bash
# Error: Forbidden.RAM

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

### Issue: STS Token Expired

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

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

```bash
# 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):
   ```bash
   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote
   ```

2. **Explore commands**:
   ```bash
   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


path: references/ram-policies.md
content: # 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**.

| API Operation | Description | Permission Required |
| ------------- | ----------- | ------------------- |
| `DescribeRegions` | List regions; auth verification in skill (`aliyun ecs describe-regions`) | `ecs:DescribeRegions` |
| `DescribeInstances` | List/query ECS instances, `--cli-query`, pagination examples | `ecs:DescribeInstances` |
| `DescribeImages` | Validate image ID | `ecs:DescribeImages` |
| `DescribeVpcAttribute` | VPC attribute query and `--waiter` example | `vpc:DescribeVpcAttribute` |
| `DescribeScalingGroups` | Query ESS scaling groups in skill examples | `ess:DescribeScalingGroups` |
| `GetCallerIdentity` | Verify caller identity (e.g. OAuth verification flows) | `sts:GetCallerIdentity` |

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.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)