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.