Alibaba Cloud CLI:Control how Alibaba Cloud CLI API calls are executed

Mutual exclusion rules

• --pager and --waiter cannot be used together. The CLI returns the following error if you combine them: ERROR: flag --pager is exclusive with --waiter.

• --cli-dry-run can coexist with --pager or --waiter, but the request is not sent, so pagination and polling are not executed.

Basic usage

Append --pager to any paginated List/Describe API. The CLI automatically iterates through all pages and merges the results into a single output.

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

Two paging modes

The CLI automatically determines which mode to use. No manual configuration is needed.

• PageNumber mode: The API response contains PageNumber, PageSize, and TotalCount fields. The CLI increments the page number until all pages are retrieved.

• NextToken mode: The API response contains a NextToken field. The CLI passes the returned NextToken value as the next request parameter until NextToken is an empty string.

Field mapping

The following sub-parameters are all optional. You only need to specify them when an API uses non-default field names for pagination information, to tell the CLI what field names the API uses. In most cases, simply appending --pager is sufficient.

Syntax: --pager key=value key=value. Multiple sub-parameters are separated by spaces. The value is the actual field name in the API response, not a specific value. For example, PageNumber=CurrentPage means the API uses the CurrentPage field to represent the page number, not that you are specifying a starting page.

Custom field mapping examples

The data array is nested at Vpcs.Vpc[] in the API response:

aliyun vpc describe-vpcs --biz-region-id cn-hangzhou --pager path=Vpcs.Vpc[]

The API uses Token instead of NextToken (xxx and list-yyy are placeholder commands):

aliyun xxx list-yyy --biz-region-id cn-hangzhou --pager NextToken=Token

Basic usage

The CLI repeatedly calls the current command, extracts a value from each response using the expr expression, and stops polling when the extracted value equals the to value, returning the last response. When timeout and interval are not specified, the CLI polls every 5 seconds for a maximum of 180 seconds (3 minutes) by default.

aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --instance-ids '["i-bp1xxxxx"]' \
  --waiter expr='Instances.Instance[0].Status' to=Running

Sub-parameters

• The field referenced by expr must be of the string type. If the field in the API response is a number or a JSON boolean (true/false), the CLI returns an error immediately.

• The to value is always compared as a string. For numeric statuses, write to=1 (not to=1.0). If the API returns a boolean as a string (e.g., "true"), write to=true.

• If an API call returns an HTTP error during polling, the CLI stops immediately and outputs the error without retrying.

• When the timeout period elapses without matching the target value, the CLI exits with a non-zero exit code and outputs the following to stderr:

  wait 'Instances.Instance[0].Status' to 'Running' timeout(180seconds), last='Pending'

  The last value is the actual value obtained from the last poll.

Control polling frequency

Shorten the polling interval (wait up to 30 seconds, poll every 2 seconds):

aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --instance-ids '["i-bp1xxxxx"]' \
  --waiter expr='Instances.Instance[0].Status' to=Running timeout=30 interval=2

Extend the wait time for resources that take longer to start (wait up to 10 minutes, poll every 10 seconds):

aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --instance-ids '["i-bp1xxxxx"]' \
  --waiter expr='Instances.Instance[0].Status' to=Running timeout=600 interval=10

Basic usage

A boolean switch that takes effect when appended. No value assignment is needed. The CLI constructs the complete request, prints the request details, but does not send it to the server.

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

Output content

The output includes: HTTP method, Endpoint, API Action, and Query Parameters. You can use this to verify whether the endpoint is correct and whether parameter serialization is as expected.

Example output:

============================================================
DRY-RUN MODE: Request Details (No actual API call)
============================================================
Method: POST
URL:
Endpoint: ecs.cn-hangzhou.aliyuncs.com
API Version: 2014-05-26
API Action: DescribeInstances
Protocol: HTTPS
Style: RPC
Query Parameters:
RegionId: cn-hangzhou
============================================================
Request NOT sent (dry-run mode)
============================================================
{
   "message": "dry-run mode - no request sent"
}

Typical scenarios

• Preview before executing sensitive operations (such as delete-instance or stop-instance). After confirming the parameters are correct, remove --cli-dry-run to execute.

• Verify command assembly correctness in CI/CD pipelines (without consuming resources or incurring costs).

Step 1: Verify the create command with --cli-dry-run

aliyun vpc create-vpc \
    --biz-region-id cn-hangzhou \
    --cidr-block 172.16.0.0/12 \
    --vpc-name test-vpc \
    --cli-dry-run

After confirming the Endpoint and parameter serialization are correct, remove --cli-dry-run to execute.

Step 2: Execute the creation and extract the VPC ID

VPC_ID=$(aliyun vpc create-vpc \
    --biz-region-id cn-hangzhou \
    --cidr-block 172.16.0.0/12 \
    --vpc-name test-vpc \
    --cli-query 'VpcId')

Step 3: Wait for the instance to become ready with --waiter

The CLI polls every 5 seconds until the status changes to Available or the 60-second timeout is reached:

aliyun vpc describe-vpcs \
    --biz-region-id cn-hangzhou \
    --vpc-id "$VPC_ID" \
    --waiter expr='Vpcs.Vpc[0].Status' to=Available timeout=60

Step 4: Retrieve all VPCs with --pager

When you have many VPCs, without --pager only the first page is returned and the new VPC may not be visible. Use --pager to confirm the newly created VPC appears in the list:

aliyun vpc describe-vpcs --biz-region-id cn-hangzhou --pager

Step 5: Delete the VPC (optional)

Delete the VPC created earlier:

aliyun vpc delete-vpc --vpc-id $VPC_ID 

Can --pager and --waiter be used together?

No. They are mutually exclusive. The CLI returns the following error: ERROR: flag --pager is exclusive with --waiter. If you need to wait for a resource to become ready and then retrieve the full list, use two separate commands.