alibabacloud-cli-guidance

Files (5)

• SKILL.md
• command-syntax.md · references/
• global-flags.md · references/
• installation-guide.md · references/
• ram-policies.md · references/

SKILL.md (first lines)

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

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

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

From irfanfaraaz/claude-kit, Apache-2.0.

More from irfanfaraaz/claude-kit