Before you use Alibaba Cloud CLI, you must configure the information that is required to call Alibaba Cloud resources. The information includes the credential, region, and language. When Alibaba Cloud CLI is used for the first time, it automatically creates a profile named default
to store the required information. You can also configure and use your custom profiles.
Profile configuration modes
Alibaba Cloud CLI provides two configuration modes: interactive mode and non-interactive mode. You can select a configuration mode based on your business requirements.
The interactive mode guides you through the configuration process. This way, you can configure a profile in Alibaba Cloud CLI at a low learning cost. We recommend that you use this mode if you are a beginner, are unfamiliar with CLI operations, or occasionally configure a profile.
The non-interactive mode allows you to directly specify configuration items by using parameters in commands or environment variables. This mode offers high flexibility and efficiency. We recommend that you use this mode if you want to manage and use Alibaba Cloud CLI by using scripts, automated deployment tools, or configuration management tools.
Interactive mode
General syntax
You can run the aliyun configure
command to configure a profile in interactive mode. Syntax:
aliyun configure --mode <AuthenticateMode> --profile <profileName>
Parameters in the command:
--mode
: the credential type. Default value: AK. For more information about the credential types supported by Alibaba Cloud CLI, see the Credential types section of this topic.--profile
: the profile name. If you do not specify this parameter, the default profile is used. If the specified profile exists, it is modified. If the specified profile does not exist, a profile with the specified name is created.
Usage notes
Make sure that you specify valid credential information. Invalid credential information may cause accidental operations or failures to run commands.
After you configure a profile in interactive mode, the following information is displayed if the credential information is valid:
Non-interactive mode
General syntax
You can run the aliyun configure set
command to configure a profile in non-interactive mode. Syntax:
aliyun configure set [--settingName <settingValue>]... --mode <AuthenticateMode> --profile <profileName>
When you configure a profile in non-interactive mode, you must specify profile parameters. You need to specify only the parameters required for the credential type of the profile that you configure.
The following list describes the common parameters, which apply to all credential types:
--profile
: required. The profile name. If the specified profile exists, it is modified. If the specified profile does not exist, a profile with the specified name is created.--region
: required. The ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.--language
: the language of Alibaba Cloud CLI. Default value: en.--mode
: the credential type. Default value: AK. For more information about the credential types supported by Alibaba Cloud CLI, see the Credential types section of this topic.
Usage notes
Make sure that you specify valid credential information. Invalid credential information may cause accidental operations or failures to run commands.
After you configure a profile in non-interactive mode, you can run the
aliyun configure list
oraliyun configure get
command to check whether the profile is configured as expected. For more information, see Profile-related commands.
Credential types
AK
Description
To ensure the security of your Alibaba Cloud account, we recommend that you create a Resource Access Management (RAM) user for calling API operations and create an AccessKey pair for the RAM user. For more information about how to use an AccessKey pair in a secure manner, see Credential security solutions.
In Alibaba Cloud CLI, AK is the default credential type, which uses an AccessKey pair as the credential. Therefore, you can omit the
--mode
parameter when you configure a profile of the AK credential type.Required parameters:
AccessKey Id
: the AccessKey ID. For more information, see Create an AccessKey pair for a RAM user.AccessKey Secret
: the AccessKey secret. For more information, see Create an AccessKey pair for a RAM user.Region Id
: the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.
Configuration examples
The following examples show how to configure a profile named AkProfile
of the AK credential type.
Interactive mode
Run the following command:
aliyun configure --profile AkProfile
The following sample response shows the interaction process:
Non-interactive mode
Run the
aliyun configure set
command to configure a profile in non-interactive mode.aliyun configure set \ --profile AkProfile \ --mode AK \ --access-key-id **** \ --access-key-secret **** \ --region ****
RamRoleArn
Description
Credentials of the RamRoleArn type are temporary
STS tokens
for RAM users. For more information about this credential type, see AssumeRole.To configure a profile of this credential type, you must set the
--mode
parameter to RamRoleArn.Required parameters:
AccessKey Id
: the AccessKey ID. For more information, see Create an AccessKey pair.AccessKey Secret
: the AccessKey secret. For more information, see Create an AccessKey pair.Region Id
: the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.RamRoleArn
: the Alibaba Cloud Resource Name (ARN) of the RAM role. You can view the ARN of a RAM role in the RAM console or by calling an API operation.For more information about how to view the ARN of a RAM role in the RAM console, see How do I view the ARN of a RAM role?
For more information about how to view the ARN of a RAM role by calling an API operation, see ListRoles or GetRole.
RoleSessionName
: the session name of the RAM role. The parameter value is user-defined and is usually set to the identity of the user who calls the API operation, such as the username.
Configuration examples
The following examples show how to configure a profile named RamRoleArnProfile
of the RamRoleArn credential type.
Interactive mode
Run the following command:
aliyun configure --profile RamRoleArnProfile --mode RamRoleArn
The following sample response shows the interaction process:
Non-interactive mode
Run the
aliyun configure set
command to configure a profile in non-interactive mode.aliyun configure set \ --profile RamRoleArnProfile \ --mode RamRoleArn \ --access-key-id **** \ --access-key-secret **** \ --ram-role-arn **** \ --role-session-name ****\ --region ****
EcsRamRole
Description
The EcsRamRole credential type allows you to use RAM roles assumed by Elastic Compute Service (ECS) instances as credentials. In this case, you need to only configure a RAM role instead of an AccessKey pair.
To configure a profile of this credential type, you must set the
--mode
parameter to EcsRamRole.Required parameters:
Region Id
: the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.EcsRamRole
: the RAM role that is assumed by your ECS instance. For more information, see Grant ECS access to other Alibaba Cloud services by using instance RAM roles.
Configuration examples
The following examples show how to configure a profile named EcsRamRoleProfile
of the EcsRamRole credential type.
Interactive mode
Run the following command:
aliyun configure --profile EcsRamRoleProfile --mode EcsRamRole
The following sample response shows the interaction process:
Non-interactive mode
Run the
aliyun configure set
command to configure a profile in non-interactive mode.aliyun configure set \ --profile EcsRamRoleProfile \ --mode EcsRamRole \ --ram-role-name **** \ --region ****
External
Description
Alibaba Cloud CLI can obtain an external credential by running a command of an external program.
To configure a profile of this credential type, you must set the
--mode
parameter to External.Alibaba Cloud CLI allows you to use an external credential to log on to CloudSSO. For more information, see Use Alibaba Cloud CLI to access CloudSSO and Alibaba Cloud resources.
Required parameters:
Process Command
: the command of the external program. External programs can return two types of static credentials: AK and StsToken. The following code shows the structures of the two types of credentials:Region Id
: the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.
Configuration examples
The following examples show how to configure a profile named ExternalProfile
of the External credential type.
Interactive mode
Run the following command:
aliyun configure --profile ExternalProfile --mode External
The following sample response shows the interaction process:
Non-interactive mode
Run the
aliyun configure set
command to configure a profile in non-interactive mode.aliyun configure set \ --profile ExternalProfile \ --mode External \ --process-command **** \ --region ****
ChainableRamRoleArn
Description
The ChainableRamRoleArn credential type allows you to use chainable role assumption to obtain credentials. To use a credential of this type, Alibaba Cloud CLI obtains an intermediate credential from the source profile, assumes a role by using the intermediate credential, and then obtains the final credential.
To configure a profile of this credential type, you must set the
--mode
parameter to ChainableRamRoleArn.Required parameters:
Source Profile
: the source profile of any credential type. The credential can be an AccessKey pair of a RAM user or an STS token that is obtained by using a credential of another type, such as EcsRamRole.Region Id
: the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.RamRoleArn
: the ARN of the RAM role. You can view the ARN of a RAM role in the RAM console or by calling an API operation.For more information about how to view the ARN of a RAM role in the RAM console, see How do I view the ARN of a RAM role?
For more information about how to view the ARN of a RAM role by calling an API operation, see ListRoles or GetRole.
RoleSessionName
: the session name of the RAM role. The parameter value is user-defined and is usually set to the identity of the user who calls the API operation, such as the username.
Configuration examples
The following examples show how to configure a profile named ChainableProfile
of the ChainableRamRoleArn credential type.
Interactive mode
Run the following command:
aliyun configure --profile ChainableProfile --mode ChainableRamRoleArn
The following sample response shows the interaction process:
You cannot configure a profile of the ChainableRamRoleArn credential type in non-interactive mode.
CredentialsURI
Description
Credentials of the CredentialsURI type are obtained by accessing local or remote Uniform Resource Identifiers (URIs).
To configure a profile of this credential type, you must set the
--mode
parameter to CredentialsURI.Required parameters:
CredentialsURI
: the local or remote URI. If the URI is inaccessible or the structure of the returned credential is incorrect, Alibaba Cloud CLI returns an error. The following code shows the standard structure:Region Id
: the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.
Configuration examples
The following examples show how to configure a profile named URIProfile
of the CredentialsURI credential type.
Interactive mode
Run the following command:
aliyun configure --profile URIProfile --mode CredentialsURI
The following sample response shows the interaction process:
You cannot configure a profile of the CredentialsURI credential type in non-interactive mode.
OIDC
Description
Credentials of the OIDC type are used for role-based single sign-on (SSO) based on OpenID Connect (OIDC). For more information about this credential type, see AssumeRoleWithOIDC.
To configure a profile of this credential type, you must set the
--mode
option to OIDC.Required parameters:
OIDCProviderARN
: the ARN of the OIDC identity provider (IdP). You can view the ARN of an OIDC IdP in the RAM console or by calling an API operation.For more information about how to the ARN of an OIDC IdP in the RAM console, see Manage an OIDC IdP.
For more information about how to the ARN of an OIDC IdP by calling an API operation, see GetOIDCProvider or ListOIDCProviders.
OIDCTokenFile
: the path of the OIDC token file. An OIDC token is issued by an external IdP.Region Id
: the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.RamRoleArn
: the ARN of the RAM role. You can view the ARN of a RAM role in the RAM console or by calling an API operation.For more information about how to view the ARN of a RAM role in the RAM console, see How do I view the ARN of a RAM role?
For more information about how to view the ARN of a RAM role by calling an API operation, see ListRoles or GetRole.
RoleSessionName
: the session name of the RAM role. The parameter value is user-defined and is usually set to the identity of the user who calls the API operation, such as the username.
Configuration examples
The following examples show how to configure a profile named OIDCProfile
of the OIDC credential type.
Interactive mode
Run the following command:
aliyun configure --profile OIDCProfile --mode OIDC
The following sample response shows the interaction process:
Non-interactive mode
Run the
aliyun configure set
command to configure a profile in non-interactive mode.aliyun configure set \ --profile OIDCProfile \ --mode OIDC \ --oidc-provider-arn **** \ --oidc-token-file **** \ --ram-role-arn **** \ --role-session-name ****\ --region ****
Use a profile
If you do not specify a profile when you run a command, the
default
profile is used.You can also use one of the following methods to specify a profile for running a command.
Use the -profile parameter
Add the
--profile
parameter to your command to use the specified profile.Example: Call the
DescribeInstances
operation of the Elastic Compute Service by using the profile namedexampleProfile
to query the information about Elastic Compute Service instances.aliyun ecs DescribeInstances --profile exampleProfile
Specify the default profile
After the default profile is specified, you do not need to specify a profile every time you run a command in Alibaba Cloud CLI. You can still use the
--profile
parameter to specify the profile that you want to use after the default profile is specified.You can use one of the following methods to specify the default profile:
Run the
aliyun configure switch
command to explicitly specify a profile as the default profile. For more information, see the "Specify the default profile" section of the Profile-related commands topic.Run the
aliyun configure set
command to modify a profile. After the profile is modified, Alibaba Cloud CLI automatically sets the profile as the default profile. For more information, see the "Method 2: Modify a specific profile" section of the Profile-related commands topic.Manually modify the
current
parameter in theconfig.json
file to specify the default profile.
Profile storage location
A profile
specifies a set of configuration items and has a custom name. All profiles are stored in the config.json
file in the JSON format. This file is located in the .aliyun
folder in your personal user directory. The path of the folder varies with the operating system.
Windows:
C:\Users\<USERNAME>\.aliyun
Linux or macOS:
~/.aliyun