Alibaba Cloud CLI:Understand Alibaba Cloud CLI command parameters

Global flags

The following flags apply to all plugin commands, including specifying a region, paginating query results, and enabling dry-run mode:

Business parameters

Business parameters are request fields that are passed to subcommands. Different operations have different business parameters.

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

The data types of business parameters are defined by APIs. Common types include:

• String: A text string, such as an instance ID or name.

• Integer: A whole number, such as a page number or count.

• Boolean: A Boolean value of true or false.

• Array / JSON: An array or JSON object, such as a list of disk IDs or a tag object.

Use CLI help information

Append --help to a command to view all supported parameters and their descriptions. The format of help output varies by command type.

Built-in commands

Built-in commands are integrated into the Alibaba Cloud CLI core program and can be used directly without installing additional plugins, such as configure. The help output for built-in commands displays subcommands or specific options:

aliyun configure --help

Help output:

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

Plugin commands

The help output for cloud service plugin commands displays parameter names in kebab-case format, including parameter types and default values:

aliyun ecs describe-instances --help

Help output:

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

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

Use the OpenAPI portal

The Alibaba Cloud OpenAPI portal allows you to debug APIs online and automatically generates CLI command examples. For more information, see Generate and run CLI commands with OpenAPI Explorer.

Common type parameter values

Different operating systems and terminal environments handle quotes differently. When passing parameter values that contain special characters, use the following quoting rules:

JSON parameter values

Some command parameters require values in JSON format. The choice of outer quotes and inner quotes varies by operating system.

Values that contain special characters

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

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

Load parameter values from a file

When a parameter value is long, such as a certificate or a large JSON payload, it is more convenient to load the value from a local file.

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

# Command substitution
aliyun cs PUT /clusters/c1234****/nodepools/np5678**** --body "$(cat request.json)"

# Here-doc (suitable for constructing inline JSON in scripts)
aliyun cs PUT /clusters/c1234****/nodepools/np5678**** --body "$(cat <<EOF
{
  "nodepool_info": {
    "name": "default-nodepool",
    "resource_group_id": "rg-acfmyvw****"
  }
}
EOF
)"

--help shows a parameter as Optional. Can I always omit it?

Not necessarily. Some commands have mutually exclusive parameters, meaning you must specify one or the other. Such parameters are individually marked as optional, but at least one of them must be specified. Otherwise, an error is returned. For specific requirement rules, refer to the API documentation of the relevant product.