Get started with Alibaba Cloud CLI - Alibaba Cloud CLI - Alibaba Cloud Documentation Center

This topic describes how to use Alibaba Cloud CLI to call API operations, including how to install Alibaba Cloud CLI, configure credentials, and generate and run commands.

Overview

To call API operations by using Alibaba Cloud CLI, perform the following steps:

Select and install a version of Alibaba Cloud CLI based on the operating system of your device.
Configure credential information in Alibaba Cloud CLI, including identity credentials such as an AccessKey pair, and a region ID. Alibaba Cloud CLI uses the credential information that you configured to call API operations.
Specify the parameters in OpenAPI Explorer to generate a sample CLI command that contains the specified parameters. Copy the command.
Paste the command into a shell tool and specify command options based on your business requirements. Run the command to call the corresponding API operation.

Prerequisites

An Alibaba Cloud account is created. If you have no Alibaba Cloud account, go to the Alibaba Cloud official website to create an Alibaba Cloud account. We recommend that you create a Resource Access Management (RAM) user to call API operations. For more information, see Create a RAM user.
The Alibaba Cloud services whose API operations you want to call are activated. You can use one of the following methods to activate the Alibaba Cloud services that you require. In this example, Short Message Service (SMS) is activated.
- Log on to the User Center console. On the service activation page, search for SMS, select the check box before SMS, and then click Activate.
- Log on to the console of each Alibaba Cloud service that you want to activate. For example, you can log on to the SMS console and click Activate Now on the Activate page of the SMS console.
Alibaba Cloud CLI is supported by the Alibaba Cloud services whose API operations you want to call. To check whether an Alibaba Cloud service supports Alibaba Cloud CLI, perform one of the following operations:
- View the documentation of the Alibaba Cloud service and choose Developer Reference > API integration overview to check whether the Alibaba Cloud service supports Alibaba Cloud CLI.
- Run the aliyun --help command in Cloud Shell provided by Alibaba Cloud to query a list of Alibaba Cloud services that support Alibaba Cloud CLI.

Step 1: Install Alibaba Cloud CLI

You must install Alibaba Cloud CLI before you can use Alibaba Cloud CLI. You can install Alibaba Cloud CLI in the Windows, Linux, and macOS operating systems. Select an installation package of Alibaba Cloud CLI based on the operating system of your device. For more information, see the following topics:

You can also use Cloud Shell provided by Alibaba Cloud to debug the commands that you want to run in Alibaba Cloud CLI. For more information about Cloud Shell, see What is Cloud Shell?

Step 2: Configure Alibaba Cloud CLI

Important

To ensure the security of your account, we recommend that you create a RAM user and obtain the identity credentials of the RAM user. For more information, see Credential security solutions.

Before you use Alibaba Cloud CLI, you must configure credential information such as identity credentials and a region ID in Alibaba Cloud CLI. Alibaba Cloud CLI supports a variety of identity credentials. For more information, see the Identity credential types section of the "Configure identity credentials" topic. In this example, AccessKey credentials are used. Perform the following steps:

Create a RAM user and grant the permissions to manage Alibaba Cloud services based on your business requirements. For more information, see Create a RAM user and Grant permissions to a RAM user.
Create an AccessKey pair for the RAM user and record the AccessKey ID and AccessKey secret for the subsequent configuration of identity credentials. For more information, see the Create an AccessKey pair for a RAM user section of the "Create an AccessKey pair" topic.
Specify a region ID. Alibaba Cloud CLI calls API operations in the specified region. For more information about available regions, see the Regions and zones section of the "Regions and zones" topic.
Note
When you use Alibaba Cloud CLI, you can specify the --region option to run a command in a specific region. If you specify this option, Alibaba Cloud CLI ignores the region information in the default credential configurations and environment variable settings. For more information, see Command line options for API calls.
Use the AccessKey pair of the RAM user to configure identity credentials in the configuration file named AkProfile. For more information, see the Configuration examples section of the "Configure identity credentials" topic.

Step 3: Generate a command

Note

OpenAPI Explorer allows you to generate all commands of Alibaba Cloud CLI online. We recommend that you use this method to obtain the sample commands that you require. For more information, see the Generate a command section of the "Generate and run CLI commands" topic.

In the left-side search box of the API debugging page, search for the API operation that you want to call. On the Parameters tab of the API operation, specify the parameters based on the API reference. Click the CLI Example tab on the right side of the Parameters tab to view the generated sample command that contains the specified parameters.

Click the icon to start Cloud Shell and debug the command in Cloud Shell.
Click the icon to copy the sample command to the clipboard. You can paste the sample command into your shell tool to run the sample command.
- Pay attention to the formats of parameters when you paste the sample command into your shell tool. For more information about the parameter formats of Alibaba Cloud CLI commands, see Parameter formats.
- By default, the --region option is added to the sample command that is generated in OpenAPI Explorer. When you copy the command to your shell tool, Alibaba Cloud CLI ignores the region information in the default credential configurations and environment variable settings, and preferentially runs the command in the specified region. You can delete or retain this option based on your business requirements.

Step 4: Call an API operation

Syntax

In Alibaba Cloud CLI, you can use the following syntax to run commands. For more information, see the Syntax section of the "Generate and run CLI commands" topic.

aliyun <command> <subcommand> [options and parameters]

Command options

When you use Alibaba Cloud CLI, you can specify command options to change the behaviors of commands or implement the extended features of commands. The following command options are frequently used:

--profile <profileName>: After you specify the --profile option and replace profileName with the name of a valid configuration file, Alibaba Cloud CLI ignores the default credential configurations and environment variable settings, and preferentially uses the specified configurations to run a command.
--help: You can specify the --help option to obtain the help information about a command. For more information, see Use the help command.

For more information about command options, see Command line options for API calls.

Run the command

After the sample command is generated, copy the sample command and paste it into a shell tool to run the command. For example, run the following command to call the CreateInstance operation of Elastic Compute Service to create a pay-as-you-go ECS instance:

aliyun ecs CreateInstance
    --InstanceName myvm1
    --ImageId centos_7_03_64_40G_alibase_20170625.vhd
    --InstanceType ecs.n4.small
    --SecurityGroupId sg-xxxxxx123
    --VSwitchId vsw-xxxxxx456
    --InternetChargeType PayByTraffic
    --Password xxx

For more information about how to run commands, see the Example section of the "Generate and run CLI commands" topic or the CLI integration example topic of each Alibaba Cloud service.