阿里雲CLI命令列參數分為控制CLI行為的全域參數和傳遞給API的業務參數，支援自動補全、參數預演及多種資料類型傳值方式。 - Alibaba Cloud CLI

阿里雲 CLI 命令列參數分為控制 CLI 行為的全域參數和傳遞給子命令的業務參數。本文介紹如何查看可用參數、書寫各型別參數值，以及使用自動補全功能。

前提條件

已安裝阿里雲 CLI 3.3.0 或更高版本。安裝方法，請參見安裝/更新 CLI。如目前的版本低於 3.3.0，請參見從舊版遷移到外掛程式版 CLI完成遷移。
確保阿里雲 CLI 已配置憑證。配置方法，請參見配置與管理身份憑證。

參數類型

CLI 命令由命令、子命令和參數（parameters）組成：

aliyun <command> <sub-command> [parameters]

參數分為兩類：

全域參數：控制 CLI 自身行為，如地區選擇、輸出格式、分頁查詢等。適用於所有命令。
業務參數：傳遞給子命令的請求欄位，不同操作的業務參數不同。

如下樣本中，--help為全域參數，--biz-region-id為業務參數：

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

全域參數

以下參數適用於所有外掛程式命令，包括指定地區、分頁查詢、啟用預演模式等：

參數	類型	作用
`--region`	string	指定地區 ID，如`cn-hangzhou`。覆蓋配置中的預設地區。
`--endpoint`	string	指定 API 存取點地址，通常無需手動設定。
`--cli-query`	string	使用 JMESPath 運算式過濾輸出結果。
`--pager` / `--all-pages`	list	自動合并分頁 API 的所有頁面結果。`--all-pages`是`--pager`的別名。
`--cli-dry-run`	bool	預演模式：執行參數校正並列印請求內容，不實際發送請求。外掛程式式命令使用此參數替代舊版`--dryrun`。
`--cli-ai-mode`	bool	AI 輔助模式，啟用後會在本次 API 請求的 User-Agent 中加入AI標識。
`--log-level`	string	設定日誌輸出層級，用於調試和排查問題。可選項：`DEBUG` / `INFO` / `WARN` / `ERROR`
`-q` / `--quiet`	bool	靜默模式：不輸出 API 返回結果。適用於指令碼和 CI/CD 情境。
`-h` / `--help`	bool	顯示協助資訊。

說明

--cli-dry-run與--pager和--quiet互斥，不能同時使用（預演模式不發送實際請求）。

業務參數

業務參數是傳遞給子命令的請求欄位，不同操作的業務參數不同。

aliyun ecs describe-instances --biz-region-id cn-hangzhou --cli-dry-run

業務參數的資料類型由 API 定義，常見類型包括：

String：字串，如執行個體 ID、名稱。
Integer：整數，如頁碼、數量。
Boolean：布爾值，true或false。
Array / JSON：數組或 JSON 對象，如磁碟 ID 列表、標籤對象。

內建命令支援參數擷取方式

內建命令整合在阿里雲 CLI 核心程式中，無需額外安裝外掛程式即可直接使用。

適用情境

CLI 自身管理：執行配置憑證、管理外掛程式、查看協助等與 CLI 運行環境相關的操作。
核心整合工具：調用已嵌入 CLI 核心的雲產品工具命令，如 ossutil、otsutil 等。
舊版命令相容：在未安裝對應外掛程式，或阿里雲 CLI 版本低於 3.3.0 時，使用舊版 CLI 命令。

常用操作

查看所有內建命令：執行 aliyun --help，在輸出結果的 Commands 段落中擷取完整列表。
查詢命令參數：執行 aliyun <command> --help（如 aliyun configure --help）。該協助資訊是確認參數可用性的唯一依據。

發現參數

可通過 CLI 協助資訊和線上 OpenAPI 門戶查看命令支援的參數。

使用 CLI 協助資訊

在命令後添加--help，查看該命令支援的所有參數及其說明。根據命令類型不同，協助資訊的格式有所差異。

內建命令

內建命令整合在阿里雲 CLI 核心程式中，無需額外安裝外掛程式即可直接使用，如configure。內建命令協助資訊顯示子命令或特定選項：

aliyun configure --help

協助資訊輸出：

configure credential and settings

Usage:
  aliyun configure --mode {AK|RamRoleArn|EcsRamRole|OIDC|External|CredentialsURI|ChainableRamRoleArn|CloudSSO|OAuth} --profile <profileName> [--config-path <configPath>]

Commands:
  get             print configuration values
  set             set config in non interactive mode
  list            list all config profile
  delete          delete the specified profile
  switch          switch default profile
  safety-policy   manage safety policy and human-in-the-loop rules
  ai-mode         manage global AI mode and User-Agent for API calls
  plugin-settings manage global plugin system settings

外掛程式命令

雲產品外掛程式命令的協助資訊顯示參數名（kebab-case 風格），包含參數類型和預設值說明：

aliyun ecs describe-instances --help

協助資訊輸出：

Description: Queries a list of instances and their details based on specified conditions

API Version: 2014-05-26

Usage:
  aliyun ecs describe-instances [parameters]

Parameters:
  --biz-region-id                string (required), The ID of the region where the
                                 instance resides. You can call https://help.aliyun.
                                 com/document_detail/25609.html to query the latest
                                 list of Alibaba Cloud regions
  --additional-attributes        list, The list of other instance attributes
                                 format: --additional-attributes value1 value2 value3
  --device-available             bool, > This parameter is in invitational preview
                                 and is not available for use
......

Global Flags:
  --cli-ai-mode             bool, For this run, enable AI-mode
  --cli-dry-run             bool, Enable dry-run mode: print request details
                            without sending the actual API call
  --cli-query               string, Use `--cli-query <jmespath>` to filter
                            output with JMESPath expression
  --endpoint                string, Override service endpoint (e.g., --endpoint
                            https://ecs.cn-hangzhou.aliyuncs.com)
......

Examples:
  aliyun ecs describe-instances --biz-region-id example-value
  aliyun ecs describe-instances --biz-region-id example-value --vpc-id example-value

舊版CLI命令（OpenAPI風格）

舊版CLI命令的協助資訊顯示參數名（通常為PascalCase 風格），參數資訊來自 API 中繼資料：

aliyun ecs DescribeInstances --help

協助資訊輸出：

Product: Ecs (Elastic Compute Service)

Parameters:
  --RegionId String  Required

  The region ID of the instance. You can call the [DescribeRegions](~~25609~~) operation to query the most recent region list.

  --AdditionalAttributes.n RepeatList Optional

  The additional instance attributes.
......

使用 OpenAPI 門戶

阿里雲 OpenAPI 門戶支援線上調試 API 並自動產生 CLI 命令樣本。具體操作，請參見產生並調用命令。

參數值

參數值的傳入方式因資料類型和作業系統環境而異。

常見型別參數值

資料類型	格式	樣本
Integer	直接傳入數值，無需引號	`--page-size 10`
String	不含特殊字元時直接傳入，含特殊字元時用引號括起	`--instance-id i-bp1234****`
Boolean	開啟或關閉某一選項的標誌。例如，出現`--dry-run`就是開啟，不出現就是關閉。	`--dry-run`
String 列表	多個值用逗號分隔，整體用引號括起	`--image-id 'm-bp1**,m-bp2**'`
JSON 數組	JSON 格式字串，外層用引號括起	`--disk-ids '["d-bp1**","d-bp2**"]'`
日期	ISO 8601 格式：`YYYY-MM-DDThh:mm:ssZ`	`--start-time 2024-11-28T15:00:00Z`

不同作業系統和終端環境對引號的處理方式不同。傳入含特殊字元的參數值時，按以下規則選擇引號：

環境	通常引號	--body 選項引號
Linux / macOS	單引號`''`	雙引號`""`
Windows 命令提示字元	雙引號`""`	雙引號`""`
Windows PowerShell	單引號`''`	單引號`''`

JSON 參數值

部分命令參數要求傳入 JSON 格式的值。外層引號和內部引號的選擇因作業系統而異。

JSON 數組

Linux / macOS：外層單引號，內部雙引號。

aliyun ecs describe-disks --disk-ids '["d-bp1****","d-bp2****","d-bp3****"]' --biz-region-id cn-hangzhou

Windows（命令提示字元及 PowerShell）：外層雙引號，內部單引號。

aliyun ecs describe-disks --disk-ids "['d-bp1****','d-bp2****','d-bp3****']" --biz-region-id cn-hangzhou

JSON 對象

當參數值為 JSON 對象時，各 JSON 對象用大括弧{}包含，對象內的索引值用冒號:分隔。

Linux / macOS：

aliyun slb add-backend-servers --load-balancer-id lb-bp1**** --backend-servers '[{"ServerId":"i-bp1****"},{"ServerId":"i-bp2****"}]'

Windows（命令提示字元及 PowerShell）：

aliyun slb add-backend-servers --load-balancer-id lb-bp1**** --backend-servers "[{'ServerId':'i-bp1****'},{'ServerId':'i-bp2****'}]"

含特殊字元的參數值

參數值以橫線（-）開頭

當參數值以-開頭時，CLI 可能將其誤判為另一個參數名：

aliyun ecs AuthorizeSecurityGroup --SecurityGroupId 'sg-bp67acfmxazb4p****' --Permissions.1.PortRange "-1/-1" --method POST --force

將參數名和參數值用等號串連即可解決：

aliyun ecs AuthorizeSecurityGroup --SecurityGroupId 'sg-bp67acfmxazb4p****' --Permissions.1.PortRange=-1/-1 --method POST --force

Shell 特殊字元

參數值包含 Shell 特殊字元（$、`、\、空格等）時，必須用引號括起。Linux / macOS 中使用單引號可以防止 Shell 解析特殊字元；Windows 命令提示字元中使用雙引號。

# Linux/macOS/PowerShell
aliyun ecs describe-images --image-name 'Example Image'
# Windows CMD
aliyun ecs describe-images --image-name "Example Image"

# Linux/macOS
aliyun xxx --param '$literal_dollar'

從檔案載入參數值

當參數值內容較長（如認證、大段 JSON）時，從本地檔案載入參數值更為方便。

--body-file（RESTful 調用）

RESTful 風格 API 呼叫中，使用--body-file從本地檔案載入 HTTP 要求體。

aliyun cs PUT /clusters/c1234****/nodepools/np5678**** --body-file request.json

Shell 命令替換與 Here-Doc

也可以使用 Shell 的命令替換（$(cat ...)）或 Here-Doc 將檔案內容傳入--body參數：

# 命令替換
aliyun cs PUT /clusters/c1234****/nodepools/np5678**** --body "$(cat request.json)"

# Here-Doc（適合指令碼內聯構造 JSON）
aliyun cs PUT /clusters/c1234****/nodepools/np5678**** --body "$(cat <<EOF
{
  "nodepool_info": {
    "name": "default-nodepool",
    "resource_group_id": "rg-acfmyvw****"
  }
}
EOF
)"

說明

Shell 命令替換與 Here-Doc僅適用於 bash 或 zsh 環境。Windows 環境請使用--body-file。

命令自動補全

阿里雲 CLI 支援命令自動補全功能，啟用後按 Tab 鍵可自動補全產品名、操作名和參數名。

說明

自動補全僅支援 Linux 和 macOS 系統的 bash 或 zsh 環境。自動補全覆蓋產品名、操作名和參數名，不覆蓋參數值。

執行以下命令啟用自動補全：

aliyun auto-completion

啟用後，執行以下命令使配置立即生效（或重新開啟終端）：

# bash
source ~/.bash_profile

# zsh
source ~/.zshrc

驗證自動補全是否生效：輸入aliyun 後按 Tab 鍵，如果有候選命令列表（如configure），則表示自動補全已啟用。

如需關閉自動補全，執行：

aliyun auto-completion --uninstall

常見問題

`--help` 顯示 Optional 的參數是否一定可以不傳？

不一定。部分命令存在互斥參數（即二選一），此類參數單獨均為非必填，但至少需指定其中一個，否則將報錯。具體必填規則請以對應產品的 API 文檔為準。

前提條件

參數類型

全域參數

業務參數

發現參數

使用 CLI 協助資訊

內建命令

外掛程式命令

使用 OpenAPI 門戶

參數值

常見型別參數值

JSON 參數值

JSON 數組

JSON 對象

含特殊字元的參數值

參數值以橫線（-）開頭

Shell 特殊字元

從檔案載入參數值

--body-file（RESTful 調用）

Shell 命令替換與 Here-Doc

命令自動補全

常見問題

--help 顯示 Optional 的參數是否一定可以不傳？

相關文檔

`--help` 顯示 Optional 的參數是否一定可以不傳？