Use Alibaba Cloud CLI to filter and format command output-Alibaba Cloud CLI(CLI)-阿里云帮助中心

Alibaba Cloud CLI commands return results in JSON format. You can use the --cli-query option to extract specific fields with JMESPath expressions (the output remains JSON), or use the --output option to display results as a table. You can also combine the two: filter first, then tabulate.

Note

Before you run the commands in this topic, make sure Alibaba Cloud CLI is installed and configured. For more information, see Install, update, and uninstall Alibaba Cloud CLI and Configure and manage credentials.

Filter JSON output with --cli-query

The --cli-query option accepts a JMESPath expression and applies it to the API response. The filtered result remains JSON, so scripts and downstream tools such as jq can process it directly.

Syntax:

aliyun <product> <operation> --cli-query "<JMESPath expression>"

The following examples use the ECS DescribeInstances response to demonstrate common filtering patterns.

Example 1: Extract a list of values

Extract all instance IDs.

aliyun ecs DescribeInstances --biz-region-id cn-hangzhou --cli-query "Instances.Instance[].InstanceId"

Sample output:

[
  "i-1234567891234567****",
  "i-abcdefghijklmnop****"
]

Example 2: Extract multiple fields

Extract the InstanceId and Status of each instance.

aliyun ecs DescribeInstances --biz-region-id cn-hangzhou --cli-query "Instances.Instance[].[InstanceId,Status]"

Sample output:

[
  [
    "i-1234567891234567****",
    "Stopped"
  ],
  [
    "i-abcdefghijklmnop****",
    "Running"
  ]
]

Example 3: Filter by condition

Extract only the IDs of running instances.

aliyun ecs DescribeInstances --biz-region-id cn-hangzhou --cli-query "Instances.Instance[?Status=='Running'].InstanceId"

Sample output:

[
  "i-abcdefghijklmnop****"
]

Example 4: Reshape the output structure

Use a JMESPath multiselect hash expression to restructure the response into an array of objects with custom key names.

aliyun ecs DescribeInstances --biz-region-id cn-hangzhou --cli-query "Instances.Instance[].{id:InstanceId,status:Status}"

Sample output:

[
  {
    "id": "i-1234567891234567****",
    "status": "Stopped"
  },
  {
    "id": "i-abcdefghijklmnop****",
    "status": "Running"
  }
]

Note

The preceding examples cover common syntax only. JMESPath also supports pipe expressions, built-in functions, and other advanced features. For the full syntax, see JMESPath Tutorial.

If --cli-query returns null, verify that the field names in your expression exactly match the keys in the API response (field names are case-sensitive).

Choose the right option

Use the following table to decide which option fits your scenario:

Scenario	Option	Description
Extract values in a script	`--cli-query`	Output is JSON, which tools such as `jq` can process directly.
Browse results in a terminal	`--output`	A table is easier to scan than raw JSON.
Filter and display as a table	Both	`--cli-query` filters or reshapes the data first, then `--output` formats the result as a table. See Example 4 in the --cli-query section above.

--output option parameters

Alibaba Cloud CLI provides the --output option to extract specific fields from the response and display them as a table.

The --output option supports the following parameters:

Parameter	Description	Example
cols	The columns to display in the table. Format: `cols="<column1>,<column2>"`. Separate multiple column names with commas (`,`). For `object` types, column names must match the keys in the JSON response. For `array` types, define custom column names and map them to the zero-based array index with a colon (`:`).	`object` type: cols="InstanceId,Status" `array` type: cols="name:0,type:1"
rows	The data source path for table rows. Uses JMESPath syntax to specify the location of data in the JSON response.	rows="Instances.Instance[]"
num	Specifies whether to display a row number column. When set to `true`, a row number column is added to the left side of the table. Row numbering starts from `0` (not 1). Default value: `false`.	num="true"

Examples

Background

Alibaba Cloud API query operations return JSON structured data, which can be difficult to read.

Taking all ECS instances as an example, run the following command.
```
aliyun ecs DescribeInstances --biz-region-id cn-hangzhou
```

Sample response (partial):

{
  "PageNumber": 1,
  "TotalCount": 2,
  "PageSize": 10,
  "RequestId": "2B76ECBD-A296-407E-BE17-7E668A609DDA",
  "Instances": {
    "Instance": [
      {
        "ImageId": "ubuntu_16_0402_64_20G_alibase_20171227.vhd",
        "InstanceTypeFamily": "ecs.xn4",
        "VlanId": "",
        "InstanceId": "i-1234567891234567****",
        "Status": "Stopped",
        "SecurityGroupIds": {
          "SecurityGroupId": [
            "sg-bp12345678912345****",
            "sg-bp98765432198765****"
          ]
        }
      },
      {
        "ImageId": "ubuntu_16_0402_64_20G_alibase_20171227.vhd",
        "InstanceTypeFamily": "ecs.xn4",
        "VlanId": "",
        "InstanceId": "i-abcdefghijklmnop****",
        "Status": "Running",
        "SecurityGroupIds": {
          "SecurityGroupId": [
            "sg-bp1abcdefghijklm****",
            "sg-bp1zyxwvutsrqpon****"
          ]
        }
      }
    ]
  }
}

Example 1: Extract a root-level field

Run the following command to extract the RequestId field. Because this field is at the root level of the response, you do not need the rows parameter.
```
aliyun ecs DescribeInstances --biz-region-id cn-hangzhou --output cols=RequestId
```

Sample output:

RequestId
---------
2B76ECBD-A296-407E-BE17-7E668A609DDA

Example 2: Extract nested fields

Run the following command to extract the InstanceId and Status fields. The JMESPath path for these fields is Instances.Instance[], so set rows to rows="Instances.Instance[]". For more information about JMESPath syntax, see JMESPath Tutorial.
```
aliyun ecs DescribeInstances --biz-region-id cn-hangzhou --output cols="InstanceId,Status" rows="Instances.Instance[]"
```

Sample output:

InstanceId             | Status
----------             | ------
i-12345678912345678123 | Stopped
i-abcdefghijklmnopqrst | Running

To display row numbers, set num to true. Sample output:

Num | InstanceId             | Status
--- | ----------             | ------
0   | i-12345678912345678123 | Stopped
1   | i-abcdefghijklmnopqrst | Running

Example 3: Extract elements from an array

Run the following command to extract specific elements from the SecurityGroupId array. The JMESPath path for this array is Instances.Instance[].SecurityGroupIds.SecurityGroupId.
```
aliyun ecs DescribeInstances --biz-region-id cn-hangzhou --output cols="sg1:0,sg2:1" rows="Instances.Instance[].SecurityGroupIds.SecurityGroupId"
```

Sample output:

sg1                     | sg2
---                     | ---
sg-bp12345678912345**** | sg-bp98765432198765****
sg-bp1abcdefghijklm**** | sg-bp1zyxwvutsrqpon****