Alibaba Cloud CLI integration example-ApsaraDB RDS(RDS)-阿里云帮助中心

Alibaba Cloud CLI is a general-purpose command-line tool built on Alibaba Cloud APIs. Use it to manage ApsaraDB RDS instances directly from a shell, without opening the console.

Prerequisites

Before you begin, ensure that you have:

Alibaba Cloud CLI installed. Download the installer for your operating system: Windows, Linux, or macOS. Alternatively, use Cloud Shell to run CLI commands without a local installation.
A RAM user with the AliyunRDSReadOnlyAccess policy (to query instances) or AliyunRDSFullAccess policy (for full management). Avoid using your root Alibaba Cloud account for API calls — it carries unnecessary security risks. For setup instructions, see Create a RAM user and Grant permissions to a RAM user.
Note
For more information about ApsaraDB RDS access policies, see Use RAM for access control.
An AccessKey pair for the RAM user. Record the AccessKey ID and AccessKey secret. See Create an AccessKey pair for a RAM user.
A region ID where your RDS instance is deployed. See Endpoints for available regions.

Configure Alibaba Cloud CLI

Use the AccessKey pair of the RAM user to configure identity credentials in the _AkProfile_ configuration profile. For detailed configuration steps, see Configuration examples.

Alibaba Cloud CLI supports other credential types in addition to AccessKey. See Identity credential types for the full list.

Generate a CLI command from OpenAPI Explorer

OpenAPI Explorer lets you configure API parameters interactively and generates the corresponding CLI command.

Go to the .
Search for the API operation in the left-side search box.
On the Parameters tab, fill in the parameters based on the API documentation.
Click the CLI Example tab to view the generated command.

From the CLI Example tab:

Click the icon to view information about Cloud Shell. For more information, see What is Cloud Shell? Then, complete the command debugging.
Click the icon to copy the command to your clipboard.

OpenAPI Explorer adds --region to generated commands by default. When --region is present, Alibaba Cloud CLI ignores the region in your default credential configuration and runs the command in the specified region. Remove or keep --region based on your needs. For parameter formatting rules, see Parameter formats.

Call ApsaraDB RDS API operations

Command syntax

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

For the full command structure reference, see Command structure.

Commonly used options

Option	Description
`--profile <profileName>`	Use a specific configuration profile. Overrides the default credential configuration and environment variable settings.
`--region <regionId>`	Run the command in a specific region. Overrides the region in your default credential configuration and environment variable settings.
`--help`	Show help information for a command.

For all available options, see Command line options for API calls.

Example 1: list available API operations

Run --help to see all ApsaraDB RDS API operations supported by Alibaba Cloud CLI:

aliyun rds --help

Output (truncated):

Alibaba Cloud Command Line Interface Version 3.0.216

Usage:
  aliyun rds <ApiName> --parameter1 value1 --parameter2 value2 ...

Product: Rds (ApsaraDB for RDS)
Version: 2014-08-15

Available Api List:
  ActivateMigrationTargetInstance             Switches workloads over from the source PostgreSQL instance to the destination ApsaraDB RDS for PostgreSQL instance.
  AddTagsToResource                           Adds tags to an instance.
  AllocateInstancePublicConnection            Apply for a public endpoint for an ApsaraDB RDS instance
  AllocateReadWriteSplittingConnection        Applies for a read-only routing endpoint for an instance.
  AttachWhitelistTemplateToInstance           Associates a whitelist template with an instance.
  CalculateDBInstanceWeight                   Queries system-assigned read weights.

  ...

For the complete list of API operations, see List of operations by function.

Example 2: query an RDS instance

Call DescribeDBInstanceAttribute to retrieve detailed attributes of an RDS instance:

aliyun rds DescribeDBInstanceAttribute --region cn-hangzhou --DBInstanceId 'pgm-bp16k272p478****'

The response is a JSON object. Key fields include the instance engine, storage type, connection string, and status. The following shows a representative subset of the output:

{
  "Items": {
    "DBInstanceAttribute": [
      {
        "ConnectionString": "pgm-bp16k272p478****.pg.rds.aliyuncs.com",
        "DBInstanceClass": "pg.n4.2c.2m",
        "DBInstanceId": "pgm-bp16k272p478****",
        "DBInstanceStatus": "Running",
        "DBInstanceStorage": 100,
        "DBInstanceStorageType": "cloud_essd",
        "Engine": "PostgreSQL",
        "EngineVersion": "14.0",
        "MaxConnections": 800,
        "MaxIOPS": 6800,
        "PayType": "Postpaid",
        "Port": "5432",
        "RegionId": "cn-hangzhou",
        ...
      }
    ]
  },
  "RequestId": "14B99E32-4ECD-5B8E-A9C8-6738C8C95910"
}

If an API call returns an error, check the input parameters and values against the error code. For self-service diagnostics, use Alibaba Cloud OpenAPI Diagnostics with the request ID or SDK error information.

What's next

What is Alibaba Cloud CLI? — full CLI documentation
Parameter formats — how to format parameters for CLI commands
Command line options for API calls — all available options
ApsaraDB RDS API reference — full list of RDS API operations and endpoints