Command structure

Alibaba Cloud CLI uses a unified plugin-based command structure. This topic describes the components of a command and how to use --help to quickly view available commands and parameters.

Prerequisites

Alibaba Cloud CLI 3.3.0 or later is installed. For more information, see Install, update, and uninstall Alibaba Cloud CLI.
A credential is configured for Alibaba Cloud CLI. For more information, see Configure and manage credentials.

Command format

Plugin-based CLI command format

The general command structure for the plugin-based Alibaba Cloud CLI is as follows:

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

Description of each component:

command: The top-level command, which can be one of the following two types:
- Built-in commands (no plugin installation required). For example:
  - configure (configure credentials and default parameters).
  - plugin (manage plugins).
  - upgrade (upgrade the CLI).
  Run aliyun --help to view all built-in commands.
- Cloud product plugin names. For example, aliyun-cli-ecs, aliyun-cli-oss, aliyun-cli-cs, and aliyun-cli-fc.
sub-command: The sub-command (SubCommand) that specifies the operation to perform.
- When the top-level command is a built-in command, run aliyun <command> --help to view the available parameters or sub-commands.
- When the top-level command is a cloud product plugin, sub-commands use kebab-case naming. For example, describe-instances and create-bucket.
parameters: Command parameters that control the behavior of Alibaba Cloud CLI or specify API parameters. For more information about parameter formats, see Understand command parameters.
- Business parameters: Prefixed with --. For example, --instance-id i-xxx.
- Global parameters: Common parameters that affect the overall command behavior. For example, --region cn-hangzhou and --profile prod.

Minimal example

The following command queries the list of regions accessible to the current account and requires no additional parameters:

aliyun ecs describe-regions

On-demand plugin loading

CLI plugins are independently distributed cloud product command sets that support automatic on-demand installation:

List installed plugins:
```
aliyun plugin list
```

Auto-install on first run (default behavior for CLI ≥ 3.3.0):

# If the ecs plugin is not installed, the CLI downloads and caches it automatically.
aliyun ecs describe-instances

Manually install a specific plugin:
```
aliyun plugin install --names ecs
```

For more plugin management operations, see Manage and use Alibaba Cloud CLI plugins.

Legacy CLI command format (OpenAPI style)

Important

Starting from version 3.3.0, Alibaba Cloud CLI introduced plugin-based commands (kebab-case style, such as aliyun ecs describe-regions), replacing the legacy PascalCase commands (such as aliyun ecs DescribeRegions). To ensure feature completeness and long-term stability, we strongly recommend migrating existing scripts and daily operations to plugin-based commands.

Alibaba Cloud OpenAPI operations use two styles: RPC and ROA. Most services use the RPC style. The calling method differs between the two styles. Before using legacy OpenAPI-style commands, you need to determine the API style. In general, all APIs within a product use the same style, and each API supports only one specific style. For more information about RPC and ROA styles, see OpenAPI styles.

RPC-style command structure

When the top-level command is a product code and the product uses the RPC style, the sub-command is typically the OpenAPI operation name. The command structure is as follows:

aliyun <ProductCode> <APIName> [Parameters]

Example: Query the list of available regions.

aliyun ecs DescribeRegions

ROA-style command structure

ROA-style OpenAPI operations require an additional HTTP method Method and request path PathPattern. The command structure is as follows:

aliyun <ProductCode> <Method> <PathPattern> [RequestBody] [Parameters]

The following example shows how to call the Container Service for Kubernetes (ACK) DescribeClustersForRegion API to query ACK dedicated clusters in the China (Hangzhou) region.

aliyun cs GET /regions/cn-hangzhou/clusters --cluster_type Kubernetes

The help output for ROA-style OpenAPI operations additionally displays the HTTP method Method and request path PathPattern to help confirm the calling format.

Determine the OpenAPI style

You can determine the API style by using the following methods:

Append --help after aliyun <command> to get the list of available OpenAPI operations. The help output for RPC-style operations displays operation descriptions, while the help output for ROA-style operations displays the request path PathPattern. For example:
```
# RPC style
aliyun ecs --help
```
Append --help after aliyun <command> <sub-command> to view parameter details. The help output for ROA-style operations additionally displays the HTTP method Method and request path PathPattern. For example:
```
# ROA style
aliyun cs AttachInstances --help
```

Note

Starting from CLI 3.3.0, after a cloud product plugin is installed, the command-level aliyun <command> --help displays the plugin help information by default. To view the original help, set the environment variable ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true. The sub-command-level aliyun <command> <sub-command> --help behavior remains unchanged.

Using command help

Alibaba Cloud CLI provides three levels of --help drill-down. Append --help after a plugin name (such as ecs) or a sub-command to view the available sub-command list and parameter details.

List built-in commands and supported plugins

aliyun --help

List all sub-commands

aliyun ecs --help

View parameter details

Displays the parameter list, whether each parameter is required, data type, default value, and examples for the specified sub-command:

aliyun ecs describe-instances --help

Key markers in help output

Marker	Description
`[Required]`	Required parameter
Type annotation	Parameter data type, such as String, Integer, Boolean, Array, or JSON
Default value	For example, `--output json` (default is json)
Example snippet	Usually located at the end of the help output, showing typical invocation patterns

FAQs

Running a command returns "Command not found"

This error indicates that the corresponding cloud product plugin is not installed. CLI ≥ 3.3.0 supports auto-installation on first run. If auto-installation fails due to network restrictions, manually run the following command to install the plugin:

aliyun plugin install --names ecs

How to view the parameters supported by a sub-command

Run aliyun <command> <sub-command> --help to view the full parameter list.