alibabacloud-cli-guidance

Aliyun CLI エキスパート

aliyun コマンドラインツールを使用して、Alibaba Cloud リソースを効果的に管理できるようユーザーを支援します。

必要な権限：./references/ram-policies.md（## required_permissions）を参照してください。他の CLI コマンドでは、必要に応じて権限を追加してください。

手順

エージェントの実行：AI モードと User-Agent（このスキル）

スキル識別子（どのパスを使用しても同じ文字列）：AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance

このスキルをリクエストに適用する方法は、必ず 1 つだけ使用してください。同じスキルトークンに対して、AI モード（configure ai-mode + set-user-agent）と ALIBABA_CLOUD_USER_AGENT またはコマンドごとの環境変数プレフィックスを併用しないでください。CLI はこれらの設定元を重ねて適用するため、User-Agent／アトリビューションが重複します（テレメトリーに悪影響があります）。

パス	使用する場合	開始	終了／クリーンアップ
A — AI モード（エージェントに推奨）	エージェントセッション、多数の aliyun 呼び出し	aliyun configure ai-mode enable を実行し、続けて aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance" を実行	［必須］ 成功、失敗、エラー、キャンセル、セッション終了を問わず、すべての終了時に最終応答の前に aliyun configure ai-mode disable を実行してください。AI モードが有効な間、同じ値を ALIBABA_CLOUD_USER_AGENT に export しないでください。
B — 環境変数または単発実行	単発のコマンド、configure を使わないスクリプト、または AI モードを使わない場合	セッション用に export ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance を実行するか、各 API 呼び出しの前に ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance aliyun ... を付けます	export を使用した場合は、他のスキルに誤ったアトリビューションが付かないよう、完了後に unset ALIBABA_CLOUD_USER_AGENT を実行してください。インラインのプレフィックスでは unset は不要です。同じスキル文字列に対して、パス B で AI モードを有効にしないでください。

パス A — 開始（API を呼び出す最初の aliyun の前に実行してください。クラウド呼び出しを伴わないローカルの aliyun configure は、必要に応じて先に実行してもかまいません）：

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

パス A — ［必須］すべての終了時に無効化（スキルの停止後も AI モードを有効なままにしないでください）：

aliyun configure ai-mode disable

パス B — 例（ワークフローごとに適用方法は 1 つだけにしてください。export、インライン環境変数、ルートの --user-agent のいずれかを使用し、同じトークンを重ねたりパス 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

ルートの --user-agent もパス B の方法です。同じトークンに対してパス A と併用しないでください。エージェント以外のコピー＆ペーストでは、多くの場合パス B で十分です。エージェントのセッションでは、パス A を使用して終了時に無効化してください。以下の例ではパス A または B のいずれか一方のみを使用し、両方を併用しません。

事前確認：Aliyun CLI 3.3.3 以降が必要です — aliyun version を実行してください。バージョンが古い場合は、curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash を実行するか、references/installation-guide.md を参照してください。

事前確認：Aliyun CLI プラグインの更新が必要です — ［必須］aliyun configure set --auto-plugin-install true を実行してください。［必須］aliyun plugin update を実行してください。

CLI のバージョンごとの主な変更点（エージェントとユーザー向け）

バージョン	利用できる機能
>= 3.3.3	このスキルの製品プラグインとフローの基本バージョンです（上記の事前確認を参照）。
>= 3.3.5	aliyun upgrade — サブコマンドが存在する場合、CLI 自体から CLI を更新できます。CLI が十分に新しい場合、通常のアップグレードではインストールスクリプトの再実行よりこちらを優先してください。
>= 3.3.8	aliyun plugin show --name <plugin> — インストール済みプラグインの詳細（バージョン、製品コード、説明、利用可能な場合は API バージョン）を表示します。古い CLI では、aliyun plugin list と製品の --help のみを使用してください。

1. CLI のインストールと設定

ユーザーが CLI をインストールまたは設定していない場合は、セットアップを案内してください。 詳しくは ./references/installation-guide.md を参照してください。簡単な手順：

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

CLI が 3.3.5 以降になった後は、通常のセルフアップデートに curl インストーラーの代わりに aliyun upgrade を使用できます（初回インストール時や、upgrade が利用できない場合は、引き続きインストーラーを使用してください）：

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

OAuth（ブラウザーでログイン）

同じマシン上でブラウザーを開ける場合（例：GUI を備えたローカルデスクトップ）は、AccessKey ペアを保存するよりもOAuth を優先してください。認証情報が設定に AK／SecretKey として平文で保存されず、SSO を使ってサインインできます。Alibaba Cloud CLI 3.0.299 以降が必要です。ヘッドレス環境（例：ローカルブラウザーのない SSH 専用サーバー）には適していません。

対話形式で実行します：

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

管理者の同意、RAM ID の割り当て、CN と INTL サイトの選択を含むセットアップ全体については、Alibaba Cloud CLI の OAuth 認証を設定する および ./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 以降は、公開されているすべての Alibaba Cloud 製品プラグインに対応しています。新しいコマンド（3.3.5 からの aliyun upgrade、3.3.8 からの aliyun plugin show）については、この手順の冒頭付近にある CLI バージョンのマイルストーンにまとめています。

認証モード（環境変数）

明示的なキーまたはトークンを使用するモード（OAuth 以外）では、デプロイの状況に合ったものを選んでください。これらの環境変数を設定すると、~/.aliyun/config.json の値より優先されます。

モード	使用する場面	環境変数
AK	開発、長期有効な認証情報	ALIBABA_CLOUD_ACCESS_KEY_ID、ALIBABA_CLOUD_ACCESS_KEY_SECRET、ALIBABA_CLOUD_REGION_ID
StsToken	CI/CD、一時的な認証情報	AK と同じ。さらに ALIBABA_CLOUD_SECURITY_TOKEN
RamRoleArn	AssumeRole 後、またはクロスアカウントセッション	ロールセッションから一時的なペアをエクスポートします。StsToken と同じ変数（AK + シークレット + ALIBABA_CLOUD_SECURITY_TOKEN）

複数のアカウントまたは環境

シェルセッション、CI ジョブ、またはシークレットストアごとに個別の export ブロックを使用します（ALIBABA_CLOUD_ACCESS_KEY_ID／ALIBABA_CLOUD_ACCESS_KEY_SECRET／ALIBABA_CLOUD_REGION_ID の値を変えます）。設定ファイルを使ったプロファイルベースのワークフローについては、./references/installation-guide.md を参照してください。

2. コマンドを組み立てる前に --help を確認する

組み込みコマンドでは、API によってパラメーター名の形式が統一されていません。PascalCase を使うものもあれば、 camelCase を使うものもあり、正確な名前を予測することはできません。パラメーター名を推測すると、何度も 再試行が必要なエラーにつながることがよくあります。最初に --help を実行すれば、数秒で確認できます。

aliyun <product> --help                # Discover available subcommands
aliyun <product> <subcommand> --help   # Get exact parameter names, types, structure

ヘルプ出力が、信頼できる情報源です。プラグインのヘルプは特に充実しており、すべてのパラメーターについて型情報、 構造フィールド、形式のヒント、制約が含まれています。

プラグインがインストールされている場合、aliyun <product> --help は自動的にプラグインのヘルプを表示します。従来の組み込み（OpenAPI 形式）ヘルプを表示するには、次を実行してください。

ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true aliyun ecs --help

3. サービスプラグインが利用可能であることを確認する

Alibaba Cloud の各製品には CLI プラグインがあります。プラグインでは、統一された kebab-case のコマンドと充実したヘルプが提供されます。一方、従来の組み込みシステムでは、命名が統一されておらず、ヘルプも最小限です。使用する製品がわかっている場合は、プラグインを直接インストールしてください。plugin install は冪等で、すでにインストール済みの場合にも安全に実行できます。

aliyun plugin install --names ecs     # Install (short name, case-insensitive)
aliyun plugin install --names ECS VPC RDS   # Multiple at once

プラグインを確認または検証するには、次を実行します。

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 は Aliyun CLI >= 3.3.8 が必要で、インストール済みのプラグインにのみ使用できます（カタログの確認には plugin list-remote／plugin search を使用してください）。古いバージョンでは plugin show を省略し、plugin list と aliyun <product> --help を使用してください。

プラグイン名には短縮形式（ecs）と完全形式（aliyun-cli-ecs）のどちらも使用でき、大文字と小文字は区別されません。

プラグインのライフサイクル：

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

4. 組み込みコマンドよりプラグインコマンドを優先する

CLI には2種類のコマンド形式があり、サブコマンドの大文字・小文字によって処理するシステムが決まります。

• すべて小文字のサブコマンド → プラグインにルーティングされます（CLI Native 形式）
• 大文字を含むサブコマンド → 組み込み機能にルーティングされます（OpenAPI 形式）

プラグインコマンドでは、サブコマンドとパラメーターの両方に一貫したケバブケースの命名規則を使用しているため、予測しやすくなっています。組み込みコマンドでは、API ごとに異なる命名規則のパラメーターと、パスカルケースのサブコマンドを使用しています。正確な名前を把握するには、コマンドごとに --help を確認する必要があります。

# 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

形式を混在させると、サイレントに失敗します。CLI はサブコマンドの大文字・小文字に基づいて、異なるバックエンドにルーティングするためです。パスカルケースのパラメーターを使ったケバブケースのサブコマンドはプラグインシステムに送信されますが、プラグインシステムはパスカルケースのパラメーター名を認識しません。

製品コードでは大文字・小文字が区別されません（ecs、Ecs、ECS はすべて使用できます）。

項目	プラグイン（CLI Native）	組み込み（OpenAPI）
サブコマンド	describe-instances	DescribeInstances
パラメーター	ケバブケース（一貫）	混在（一貫しない）
ROA ボディ	個別のパラメーターに展開	単一の --body JSON
ヘッダーパラメーター	ヘルプに表示され、直接使用可能	非表示。手動での --header のみ
ヘルプ	構造を含む詳細な説明	基本的な説明

5. グローバルパラメーターとビジネスパラメーターの命名規則を理解する

CLI プラグインシステムでは、特定のグローバルパラメーターを独自用途のために予約しています。

• --region-id / --region — リクエストの送信先となる API エンドポイント（例：ecs.cn-hangzhou.aliyuncs.com）を指定します。これはルーティングに関する設定であり、ビジネスフィールドではありません。
• その他のグローバルパラメーターには、--profile、--api-version、--output などがあります。

多くの API では、API 仕様に RegionId や Region という独自のパラメーターも定義されています。これらは API 固有の意味を持つ ビジネスパラメーターです（例：「このリソースを作成するリージョン」）。グローバルの --region-id と API の RegionId は異なる目的で使われますが、コマンドライン上では名前が衝突する可能性があります。

プラグインシステムは、コード生成時にこれを自動的に解決します。

1. --biz- プレフィックス（デフォルト）：API パラメーターの RegionId は --biz-region-id になります。
2. --<product>- プレフィックス（フォールバック）：別のパラメーターがすでに --biz-region-id を使用している場合、プラグインは --<product>-region-id（例：--ecs-region-id）に切り替えます。

つまり、プラグインコマンドでは、--region-id は常にグローバルのエンドポイント選択用であり、ビジネス用のリージョンは --biz-region-id（または --<product>-region-id）です。ビジネスパラメーターのつもりで --region-id を使うと、意図したフィールドを設定せずにエンドポイントが変更され、サイレントに失敗します。

必ず --help を確認して、実際のパラメーター名を確認してください。指定されたコマンドで --biz-region-id、--<product>-region-id、または別の名前のどれが使われているかを確認する際の、信頼できる情報源です。

6. 構造化パラメーター構文を使用する

プラグインは、フレームワークが自動的にシリアライズする構造化入力に対応しています。これにより、間違いやすい従来の --Tag.N.Key / --Param.N=value 構文を避けられます。

プリミティブとリスト：

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

キーと値のオブジェクト、および繰り返し可能な構造：

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

コマンドごとに --help を確認してください。正確な型、構造のフィールド、パラメーターが繰り返し可能かどうかが表示されます。

7. OSS ではカスタムコマンドを使用する

他の製品とは異なり、OSS には独自の構文を持つ手書きの実装があります。OSS では PutBucket や GetObject のような API 形式のコマンドは使用できません。これらを使うと、サイレントに失敗したり、わかりにくいエラーが発生したりします。必ず最初にヘルプを確認してください。

aliyun oss --help        # Basic operations (cp, ls, mb, rm, etc.)
aliyun ossutil --help    # Advanced utilities (sync, stat, etc.)

以下の行は構文の例のみです（<your-*> プレースホルダー）。そのまま実行しないでください。実行前に、実際のパス、バケット名、ファイル名に置き換えてください。

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. 出力をフィルタリングして形式を指定する

--cli-query（JMESPath）を使って API レスポンスから特定のフィールドを抽出し、--output で形式を指定します。これにより、大きな JSON データを外部ツールにパイプで渡す必要がなくなります。

# 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. ページネーション

多くのリストコマンドは、ページ分割された結果を返します。--page-number と --page-size を使って制御します：

aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --page-number 1 \
  --page-size 50

手動でループを組まずにすべてのページを自動的に取得するには、--pager を使います：

aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --pager path='Instances.Instance[]' PageNumber=PageNumber PageSize=PageSize

path 引数では、結合するページデータを含む JSON フィールドを指定します。

10. リソースの状態を待機

一部のコマンドは、自動化向けの組み込み待機機能に対応しています。リソースが目的の状態になるまでポーリングします：

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

11. デバッグ

コマンドの失敗を調査する場合、次のフラグを使うと、内部で何が起きているかを確認できます。HTTP リクエスト／レスポンス全体と、パラメーター検証の詳細が表示されます：

• --log-level debug — 詳細なリクエスト／レスポンスログ（エンドポイント、シリアル化されたパラメーター、レスポンスを表示します）
• --cli-dry-run — コマンドを実行せずに検証します（パラメーターの解析を確認します）
• ALIBABA_CLOUD_CLI_LOG_CONFIG=debug — ログレベルをグローバルに設定する環境変数

403、Forbidden、NoPermission、またはその他の RAM による拒否が発生した場合、認証情報に対応する ID に、基盤となる API アクションを実行する権限がありません。スキルの required_permissions テーブル、オンデマンド認可、権限を絞り込む方法については、./references/ram-policies.md を参照してください。

12. 複数バージョンの API サポート

一部の製品（ESS、SLB など）には、コマンドセットや機能が異なる複数の API バージョンがあります。誤ったバージョンを使用すると、パラメーターが見つからない、非推奨の動作になる、または利用可能なコマンドがまったく異なるといった問題が発生することがあります。複数のバージョンがある製品ばかりではありません。list-api-versions がエラーを返す場合、その製品は単一バージョンのため、対応は不要です。

バージョンを確認する

aliyun <product> list-api-versions

例（ESS。* はデフォルトです）：

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

バージョンごとに、異なるコマンドやパラメーター名が公開されている場合があります。

コマンドごとにバージョンを指定する

aliyun ess describe-scaling-groups --api-version 2022-02-22 --biz-region-id cn-hangzhou

環境変数でデフォルトバージョンを設定する

呼び出しのたびに --api-version を渡さなくても済むように、製品のデフォルトバージョンを設定します：

export ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22
export ALIBABA_CLOUD_SLB_API_VERSION=2014-05-15

形式は ALIBABA_CLOUD_<PRODUCT_CODE>_API_VERSION（製品コードは大文字）です。 複数のコマンドで一貫したバージョンの動作が必要なスクリプトや CI/CD で特に便利です。

特定のバージョンで使用可能なコマンドを確認する

API バージョンごとに、コマンドセットが異なる場合があります。使用可能なコマンドを確認するには：

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

バージョンを指定する場合

• デフォルト — 新しい機能が必要でなければ、デフォルトで十分です。
• --help — 別の API バージョンでのみ使用できるパラメーターがないか確認します。
• スクリプト／CI — 再現性を確保するため、ALIBABA_CLOUD_<PRODUCT>_API_VERSION を固定します。

グローバルフラグのリファレンス

以下のフラグは、すべてのプラグインコマンドで使用できます：

フラグ	用途
--region <region>	API エンドポイントのリージョン（ビジネスリージョンではなく、グローバル設定）
--profile <name>	名前付き認証情報プロファイルを使用します
--api-version <ver>	このコマンドの API バージョンを上書きします
--output json|table|cols=...	レスポンス形式
--cli-query <jmespath>	レスポンスに対する JMESPath フィルター
--log-level debug	詳細なリクエスト／レスポンスログ
--cli-dry-run	実行せずに検証します
--endpoint <url>	サービスエンドポイントを上書きします
--retry <n>	リクエスト失敗時の再試行回数
--quiet	出力を抑制します
--pager	ページ分割に対応した API の全ページを自動的に結合します

よくあるワークフロー

ECS インスタンス

aliyun plugin list | grep ecs
# If missing: aliyun plugin install --names ecs

aliyun ecs describe-instances --biz-region-id cn-hangzhou

以下の create-instance の例は、課金対象のリソースをプロビジョニングします（固定のイメージ ID、インスタンスタイプ、ディスクを例として使用しています）。このまま実行しないでください。実行前に、ご利用のアカウントとポリシーに合わせて、リージョン、イメージ、タイプ、ディスク、ネットワーク、タグを調整してください。

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 ボディの展開）

aliyun plugin list | grep fc
# If missing: aliyun plugin install --names fc

以下のブロックは構文の例です（<your-function-name> やその他の値は説明用です）。このまま実行しないでください。実際の関数名、ランタイム、ハンドラー、メモリ、タイムアウトを設定し、環境に必要な VPC やサービスロールの設定を追加してください。プラグインコマンドでは ROA ボディのフィールドが個別のパラメーターに展開されるため、--body の JSON は不要です。

aliyun fc create-function \
  --function-name <your-function-name> \
  --runtime python3.9 \
  --handler index.handler \
  --memory-size 512 \
  --timeout 60 \
  --description "Process uploaded images"

複数バージョンの 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

応答形式

CLI コマンドを提示するときは、次の点に従ってください。

1. コマンドの動作と、特定のパラメーターを使用する理由を説明します
2. 必須パラメーターをすべて含む完全なコマンドを示します
3. 特に --biz- で始まるパラメーターなど、分かりにくい値とその理由を明記します
4. トラブルシューティング中のユーザーには、--log-level debug を提案します
5. API の帰属情報には、AI モードと set-user-agent の組み合わせ、または環境変数／インラインの ALIBABA_CLOUD_USER_AGENT のいずれかを使用し、同じスキルトークンに両方を使用しないでください。エージェントは終了時に毎回 AI モードを無効にするか、export の後に unset を実行する必要があります（**エージェントの実行：AI モードと User-Agent（このスキル）**を参照）。

参考資料

• ./references/installation-guide.md — インストール、設定モード、認証情報の設定
• ./references/command-syntax.md — コマンド構文の完全ガイド
• ./references/global-flags.md — グローバルフラグのリファレンス
• ./references/ram-policies.md — オンデマンド RAM、最小権限、よくある権限エラー