This topic describes how to configure identity credentials, install cloud product plugins, and run your first command using the Alibaba Cloud CLI. - Alibaba Cloud CLI

After installing the Alibaba Cloud CLI, configure your identity credentials and install a cloud product plugin to start making API calls. This topic uses ECS as an example to walk you through the complete process—from installing the CLI to running your first command.

Solution overview

To call cloud product APIs using the Alibaba Cloud CLI, follow these four steps:

Step 1: Install the Alibaba Cloud CLI
Step 2: Configure identity credentials
Step 3: Install a cloud product plugin
Step 4: Run a command

Prerequisites

You have an Alibaba Cloud account. If you do not have one, go to Alibaba Cloud official website to register.

Step 1: Install the Alibaba Cloud CLI

On Linux, run the following one-click installation command:

/bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"

For installation instructions on other operating systems, see Install or update CLI.

After installation, run the following command to check the version:

aliyun version

Make sure the version number is 3.3.0 or later. If not, reinstall the CLI.

Note

If you prefer not to install the CLI locally, use Cloud Shell. It comes with the Alibaba Cloud CLI preinstalled and automatically authenticates your browser session. You can start from Step 3.

Step 2: Configure identity credentials

The Alibaba Cloud CLI supports multiple identity authentication methods. Use OAuth authentication when possible. If you use an AccessKey, do not hard code it in your source code.

OAuth authentication

OAuth completes authentication by logging in through your browser. You do not need to manually create or manage keys.

Note

You cannot use OAuth authentication on servers without a graphical interface. Switch to the AccessKey authentication tab instead.

Important

RAM administrators must complete the following tasks in advance: create a CLI OAuth application and assign identities to users who need CLI access. For details, see Step 1 and Step 2 in Configure OAuth authentication for Alibaba Cloud CLI. Users of an Alibaba Cloud account (the account used during registration) do not need to perform these tasks.

Run the following command to start OAuth configuration:
```
aliyun configure --mode OAuth --profile default
```
The --profile default option saves these credentials under the profile name default. The CLI supports multiple named profiles. Use --profile mydev to switch between different credentials.
The CLI prompts you to select a sign-in site. Press Enter to accept the default setting.

The CLI automatically opens your browser to complete authorization. Your terminal displays output similar to the following:

Please open the following URL in your browser to authorize:
https://signin.aliyun.com/oauth2/v1/auth?response_type=code&client_id=40381819545577*****&redirect_uri=http%3A%2F%2F127.0.0.1%3A12345%2Fcli%2Fcallback&state=CdI6CcOsxQUiCuFl&code_challenge=vDr1QWI5TI9q6UMMs2djJzxCmcAySjrYK6UD4Gu2res&code_challenge_method=S256
If the browser does not open automatically, use the following URL to complete the login process:

SignIn url: https://signin.aliyun.com/oauth2/v1/auth?response_type=code&client_id=40381819545577*****&redirect_uri=http%3A%2F%2F127.0.0.1%3A12345%2Fcli%2Fcallback&state=CdI6CcOsxQUiCuFl&code_challenge=vDr1QWI5TI9q6UMMs2djJzxCmcAySjrYK6UD4Gu2res&code_challenge_method=S256

Now you can login to your account with OAuth configuration in the browser.

If the browser does not open automatically, copy the Sign In URL shown in the terminal and open it manually in your browser to log in.

After successful authorization, return to the terminal and enter your default region ID and terminal language. Example terminal output:

Default Region Id []: cn-hangzhou
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en: zh
Saving profile[oauth-1] ...Done.

Configure Done!!!
..............888888888888888888888 ........=8888888888888888888D=..............
...........88888888888888888888888 ..........D8888888888888888888888I...........
.........,8888888888888ZI: ...........................=Z88D8888888888D..........
.........+88888888 ..........................................88888888D..........
.........+88888888 .......Welcome to use Alibaba Cloud.......O8888888D..........
.........+88888888 ............. ************* ..............O8888888D..........
.........+88888888 .... Command Line Interface(Reloaded) ....O8888888D..........
.........+88888888...........................................88888888D..........
..........D888888888888DO+. ..........................?ND888888888888D..........
...........O8888888888888888888888...........D8888888888888888888888=...........
............ .:D8888888888888888888.........78888888888888888888O ..............

Verify that your credentials are valid:
```
aliyun sts get-caller-identity
```
If the response includes AccountId and Arn, your credentials are valid.
Note
If you receive a Forbidden.NoPermission error, your current user lacks sufficient permissions. Contact your organization’s RAM administrator to grant the required permissions to your RAM user. If you are using an Alibaba Cloud account, check that your account status is normal.

AccessKey authentication

Warning

An AccessKey is a long-term credential. Do not hard code it in your source code or configuration files. Pass it through environment variables instead. Use AccessKeys only in personal development and test environments. For production environments, use OAuth. For more information, see Secure credential usage practices.

If you already have an AccessKey, use your existing AccessKey ID and AccessKey secret and skip this step. If you do not have one, go to the RAM console to create a RAM user and generate an AccessKey. For details, see Create a RAM user.
Run the following command to start AccessKey configuration:
```
aliyun configure --mode AK --profile default
```
The --profile default option saves these credentials under the profile name default. The CLI supports multiple named profiles. Use --profile mydev to switch between different credentials.
Enter your AccessKey ID, AccessKey secret, default region ID (such as cn-hangzhou), and terminal language when prompted.
Verify that your credentials are valid:
```
aliyun sts get-caller-identity
```
If the response includes AccountId and Arn, your credentials are valid. If you receive an error, check that your AccessKey ID and secret are correct.
Note
If you receive a Forbidden.NoPermission error, your current RAM user lacks sufficient permissions. Contact your organization’s RAM administrator to grant the required permissions. If you are using an Alibaba Cloud account, check that your account status is normal.

The Alibaba Cloud CLI also supports other credential types, such as Security Token Service tokens for temporary authorization scenarios. For details, see Configure and manage identity credentials.

Step 3: Install a cloud product plugin

Alibaba Cloud CLI commands for each cloud product are packaged as plugins and installed on demand.

Using ECS as an example, install the ECS plug-in:

aliyun plugin install --names ecs

If the terminal displays Plugin aliyun-cli-ecs x.x.x installed successfully!, the installation succeeded.

For more information about installing and managing plugins, see Quickly install cloud product CLI plugins.

Step 4: Run a command

Run the following command to list available regions:

aliyun ecs describe-regions --accept-language zh-CN

The --accept-language zh-CN option specifies that the response language is Chinese.

Example command output (excerpt):

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "China (Hangzhou)"
      },
      {
        "RegionId": "cn-shanghai",
        "RegionEndpoint": "ecs.cn-shanghai.aliyuncs.com",
        "LocalName": "China (Shanghai)"
      },
      {
        "RegionId": "cn-beijing",
        "RegionEndpoint": "ecs.cn-beijing.aliyuncs.com",
        "LocalName": "China (Beijing)"
      }
    ]
  },
  "RequestId": "5BEAEC76-E9B4-47B2-8D24-A3C31D5D2EEF"
}

The RequestId is a unique identifier for each API call and is used for troubleshooting.

FAQ

Why do I get an “Unauthorized call” error during OAuth configuration?

Your current account does not have the RAM management permissions required to create an OAuth application. Switch to a RAM administrator account or ask your administrator to create the OAuth application and assign identities. For specific permission requirements, see OAuth credentials.

Why do I need to install a plugin to use cloud product commands?

The Alibaba Cloud CLI uses a plugin-based architecture. The core CLI remains lightweight, while commands for each cloud product are packaged separately as plugins. This lets you install and update plugins on demand without upgrading the entire CLI. Run aliyun plugin list-remote to view all available plugins.

How do I know if a cloud product supports the CLI?

Run aliyun plugin list-remote to view all available plugins, or visit OpenAPI Portal CLI Homepage and search by product.

Can I use OAuth authentication on a server without a graphical interface?

No. OAuth authentication requires browser-based login and authorization.

Alibaba Cloud CLI:Get started with Alibaba Cloud CLI