/alibabacloud-cli-guidance

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: sdk-team@alibabacloud.com
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): `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 | 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 "AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance"` | **[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):

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

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

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