English | 简体中文

Alibaba Cloud CLI

阿里云命令行工具是开源项目，您可以从 Github 上获取最新版本的 CLI。您也可以在安装 CLI 前在 Cloud Shell 进行试用：

简介

阿里云命令行工具是用 Go 语言编写的, 基于阿里云 OpenAPI 打造的，用于管理阿里云资源的工具。通过下载和配置该工具，您可以在一个命令行方式下管理多个阿里云产品资源。

如果您在使用 CLI 的过程中遇到任何问题，请直接提交 Issues。

注意：阿里云 CLI 使用 OpenAPI 方式访问云产品，确保您已经开通了要使用的云产品并了解该产品的 OpenAPI 的使用。您可以在阿里云 OpenAPI 开发者门户查看产品 API 文档，了解 API 的使用方式及参数列表。

使用诊断

Troubleshoot 提供 OpenAPI 使用诊断服务，通过 RequestID 或 报错信息 ，帮助开发者快速定位，为开发者提供解决方案。

CLI Releases

CLI 版本更改说明请参考 CHANGELOG

安装

下载安装包 (推荐)

阿里云 CLI 工具下载、解压后即可使用，支持 Mac、Linux(amd64/arm64)、Windows 平台(x64版本)。您可以将解压的aliyun 可执行文件移至 /usr/local/bin 目录下，或添加到 $PATH 中。

下载链接如下 ()：
点击查看所有版本。
使用 brew

如果你的电脑上安装了 brew, 你可以使用它来安装阿里云命令行工具:
```
brew install aliyun-cli
```
使用一键安装脚本

你可以在 macOS 或 Linux 的命令行终端运行下面的命令：
```
/bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"
```

如果需要详细安装步骤或者编译安装步骤请访问官网文档安装 CLI

配置

详细配置指引请访问官网配置 CLI

在使用阿里云 CLI 之前，您需要配置调用阿里云资源所需的凭证信息、地域、语言等。

你可以运行 aliyun configure 命令进行快速配置：

$ aliyun configure
Configuring profile 'default' in '' authenticate mode...
Access Key Id []: AccessKey ID
Access Key Secret []: AccessKey Secret
Default Region Id []: cn-hangzhou
Default Output Format [json]: json (Only support json))
Default Language [zh|en] en:
Saving profile[akProfile] ...Done.

这将会以 AK 的认证模式对 default 进行凭证和其它配置。

所有凭证模式

可通过在 configure 命令后增加 --mode <authenticationMethod> 参数的方式来使用不同的凭证方式，目前支持的认证方式如下：

凭证模式	说明
AK	使用直接的 AccessKey ID/Secret 访问凭证
RamRoleArn	使用 RAM 子账号角色扮演提供访问凭证
EcsRamRole	使用 ECS 实例角色提供访问凭证
OIDC	使用 OIDC 角色扮演的方式访问
External	使用外部进程提供访问凭证
CredentialsURI	使用外部服务提供访问凭证
ChainableRamRoleArn	使用链式角色扮演的方式提供访问凭证

如果在配置时不传递 --mode，将默认使用 AK 模式。

RAM 子账号角色扮演

您可以使用 --mode RamRoleArn 指定通过 RAM 子账号进行角色扮演来获取凭证。它的底层是通过 AssumeRole 方法来换取临时凭证。示例如下：

$ aliyun configure --mode RamRoleArn --profile subaccount
Configuring profile 'subaccount' in 'RamRoleArn' authenticate mode...
Access Key Id []: AccessKey ID
Access Key Secret []: AccessKey Secret
Sts Region []: cn-hangzhou
Ram Role Arn []: acs:ram::******:role/ecs-test
Role Session Name []: sessionname
Expired Seconds []: 900
Default Region Id []: cn-hangzhou
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en:
Saving profile[subaccount] ...Done.

使用外部程序获取凭证

您可以使用 --mode External 指定通过外部程序获取凭证数据，CLI 将会以执行该程序命令并将其返回作为凭证来使用。

约定：

外部程序输出位置为标准输出
输出为json结构字符串
输出包含关键字段以及凭证字段

关键字段:

mode: 指定返回凭证类型，目前支持两种静态的凭证。

各凭证返回结构示例:

AK

{
  "mode": "AK",
  "access_key_id": "accessKeyId",
  "access_key_secret": "accessKeySecret"
}

StsToken

{
  "mode": "StsToken",
  "access_key_id": "accessKeyId",
  "access_key_secret": "accessKeySecret",
  "sts_token": "stsToken"
}

示例

$ aliyun configure --mode External --profile externalTest
Configuring profile 'externalTest' in 'External' authenticate mode...
Process Command []: <getCredential ak>
Default Region Id []: cn-hangzhou
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en: 
Saving profile[externalTest] ...Done.

使用链式 RamRoleArn

通过 ChainableRamRoleArn ，可以指定一个前置凭证配置，然后再进行角色扮演。前置凭证的设置会更灵活，它可以是子账号的 AK，也可以是通过其它方式换取的 STS，比如 EcsRamRole。

你可以使用 --mode ChainableRamRoleArn 来组合源配置和 RamRoleARN 的角色扮演流程。下面的例子从源配置中获取中间凭证，再基于中间凭证完成角色扮演，获取最终的凭证。

{
  "profiles": [
    {
      "name": "chain",
      "mode": "ChainableRamRoleArn",
      "ram_role_arn": "acs:ram::<Account ID>:role/<Role Name>",
      "ram_session_name": "session",
      "source_profile": "cli-test"
    },
    {
      "name": "cli-test",
      "mode": "AK",
      "access_key_id": "<Access Key ID>",
      "access_key_secret": "<Access Key Secret>"
    }
  ]
}

使用 Credentials URI

你可以通过 --mode CredentialsURI 来从一个本地或远程的 URI 地址实现 Credentials 的获取。

{
  "profiles": [
    {
      "name": "uri",
      "mode": "CredentialsURI",
      "credentials_uri": "http://localhost:6666/?user=jacksontian"
    }
  ]
}

这个 Credentials URI 必须相应 200 和如下的结构：

{
  "Code": "Success",
  "AccessKeyId": "<ak id>",
  "AccessKeySecret": "<ak secret>",
  "SecurityToken": "<security token>",
  "Expiration": "2006-01-02T15:04:05Z" // utc time
}

其他情况，CLI 会当作失败案例处理。

使用 OIDC 获取凭证

你可以通过 --mode OIDC 来使用基于 OIDC 的 SSO 角色扮演获取凭证。示例如下：

$ aliyun configure --mode OIDC --profile oidc_p
Configuring profile 'oidc_p' in 'OIDC' authenticate mode...
OIDC Provider ARN []: xxxx
OIDC Token File []: xxx
RAM Role ARN []: xxx
Role Session Name []: xxx
Default Region Id []: xxx
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en: 
Saving profile[oidc_p] ...Done.

启用 zsh/bash 自动补全

使用 aliyun auto-completion 命令开启自动补全，目前支持 zsh/bash
使用 aliyun auto-completion --uninstall 命令关闭自动补全

使用阿里云 CLI

这里是基础使用指引，如需要详细使用手册，请访问这里。

阿里云云产品的 OpenAPI 有 RPC 和 RESTful 两种风格，大部分产品使用的是 RPC 风格。不同风格的 API 的调用方法也不同。

您可以通过以下特点判断API风格：

API 参数中包含 Action 字段的是RPC风格，需要 PathPattern 参数的是 Restful 风格。
一般情况下，每个产品内，所有 API 的调用风格是统一的。
每个 API 仅支持特定的一种风格，传入错误的标识，可能会调用到其他 API，或收到“ApiNotFound”的错误信息。

调用 RPC 风格的 API

阿里云 CLI 中 RPC 风格的 API 调用的基本结构如下：

aliyun <product> <operation> [--parameter1 value1 --parameter2 value2 ...]

代码示例：

aliyun rds DescribeDBInstances --PageSize 50
aliyun ecs DescribeRegions
aliyun rds DescribeDBInstanceAttribute --DBInstanceId xxxxxx

调用 RESTful 风格的 API

部分阿里云产品如容器服务的 OpenAPI 为 Restful 风格，调用 Restful 风格的接口与调用 RPC 风格的接口方式不同。参考以下代码示例，调用 RESTful API。

GET请求示例：
```
aliyun cs GET /clusters
```

POST请求示例：

aliyun cs POST /clusters --body "$(cat input.json)"

DELETE请求示例：

aliyun cs DELETE /clusters/ce2cdc26227e09c864d0ca0b2d5671a07

获取帮助信息

阿里云 CLI 集成了一部分产品的 API 和参数列表信息, 您可以使用如下命令来获取帮助：

$ aliyun help: 获取产品列表
$ aliyun help <product>: 获取产品的API信息

如获取 ECS 的 API 信息：$ aliyun help ecs
$ aliyun help <product> <apiName>: 获取 API 的调用信息

如获取 ECS 的 CreateInstance 的信息： aliyun help ecs CreateInstance

使用`--force`参数

阿里云 CLI 集成了一部分云产品的元数据，在调用时会对参数的合法性进行检查。如果使用了一个元数据中未包含的API或参数会导致unknown api或unknown parameter错误。可以使用--force参数跳过API和参数检查，强制调用元数据列表外的API和参数，如:

aliyun newproduct --version 2018-01-01 --endpoint newproduct.aliyuncs.com --param1 ... --force

在使用--force参数时，必须指定以下两个参数：

--version: 指定API的版本，你可以在API文档中找到版本号，如ECS的版本号是2014-05-26。
--endpoint: 指定产品的接入地址。请参考各产品的API文档。

使用`--output`参数

阿里云产品的查询接口会返回 JSON 结构化数据，不方便阅读。例如：

aliyun ecs DescribeInstances

执行以上命令将得到以下 JSON 结果：

{
  "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-12345678912345678123",
        "Status": "Stopped",
        //omit some fields
      },
      Instance": [
      {
        "ImageId": "ubuntu_16_0402_64_20G_alibase_20171227.vhd",
        "InstanceTypeFamily": "ecs.xn4",
        "VlanId": "",
        "InstanceId": "i-abcdefghijklmnopqrst",
        "Status": "Running",
        //omit some fields
      },
    ]
  }
}

可以使用--output参数提取结果中感兴趣的字段，并进行表格化输出。例如：

aliyun ecs DescribeInstances --output cols=InstanceId,Status rows=Instances.Instance[]

执行以上命令将得到以下形式的结果：

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

在使用--output参数时，必须指定以下子参数：

cols: 表格的列名，需要与json数据中的字段相对应。如ECS DescribeInstances 接口返回结果中的字段InstanceId 以及 Status。

可选子参数：

rows: 通过 jmespath 查询语句来指定表格行在json结果中的数据来源。

使用`--waiter`参数

该参数用于轮询实例信息直到出现特定状态。

例如使用ECS创建实例后，实例会有启动的过程。我们会不断的查询实例的运行状态，直到状态变为"Running"。

例如：

aliyun ecs DescribeInstances --InstanceIds '["i-12345678912345678123"]' --waiter expr='Instances.Instance[0].Status' to=Running

执行以上命令后,命令行程序将以一定时间间隔进行实例状态轮询，并在实例状态变为Running时停止轮询。

在使用 --waiter 参数时，必须指定以下两个子参数：

expr: 通过 jmespath 查询语句来指定json结果中的被轮询字段。
to: 被轮询字段的目标值。

可选子参数：

timeout: 轮询的超时时间(秒)。
interval: 轮询的间隔时间(秒)。

环境变量支持

我们支持下面的环境变量：

ALIBABA_CLOUD_PROFILE：当 --profile 没有指定，CLI 将使用该环境变量。
ALIBABA_CLOUD_IGNORE_PROFILE=TRUE: 当这个变量被指定，CLI 忽略配置文件。
ALIBABA_CLOUD_ACCESS_KEY_ID：当没有任何 Access Key Id 的指定，CLI 将使用该环境变量。
ALIBABA_CLOUD_ACCESS_KEY_SECRET：当没有任何 Access Key Secret 的指定，CLI 将使用该环境变量。
ALIBABA_CLOUD_SECURITY_TOKEN：当没有任何 Security Token 的指定，CLI 将使用该环境变量。
ALIBABA_CLOUD_REGION_ID：当没有任何 RegionId 的指定，CLI 将使用该环境变量。
DEBUG=sdk：通过该环境变量，CLI 将打印 HTTP 请求信息。这对于排查故障非常有用。

获取帮助

我们使用 GitHub issues 追踪用户反馈的 bug 和功能请求。请访问以下站点获取帮助：

基本使用方法请访问官网阿里云 CLI
在 Stack Overflow 上提问并使用标签 aliyun-cli
如果您发现了一个 BUG 或是希望新增一个特性，请提交 issue。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README-CN.md

README-CN.md

Alibaba Cloud CLI

简介

使用诊断

CLI Releases

安装

配置

所有凭证模式

RAM 子账号角色扮演

使用外部程序获取凭证

示例

使用链式 RamRoleArn

使用 Credentials URI

使用 OIDC 获取凭证

启用 zsh/bash 自动补全

使用阿里云 CLI

调用 RPC 风格的 API

调用 RESTful 风格的 API

获取帮助信息

使用`--force`参数

使用`--output`参数

使用`--waiter`参数

环境变量支持

获取帮助

Files

README-CN.md

Latest commit

History

README-CN.md

File metadata and controls

Alibaba Cloud CLI

简介

使用诊断

CLI Releases

安装

配置

所有凭证模式

RAM 子账号角色扮演

使用外部程序获取凭证

示例

使用链式 RamRoleArn

使用 Credentials URI

使用 OIDC 获取凭证

启用 zsh/bash 自动补全

使用阿里云 CLI

调用 RPC 风格的 API

调用 RESTful 风格的 API

获取帮助信息

使用--force参数

使用--output参数

使用--waiter参数

环境变量支持

获取帮助

使用`--force`参数

使用`--output`参数

使用`--waiter`参数