Alibaba Cloud CLI writes its help information and error messages for human readers. An AI agent must parse this content, which increases the parsing cost and the number of retries. When you enable AI Mode, the CLI identifies the caller as an AI agent in the User-Agent of each request. Help information, error information, and next-step guidance then take a form that is easier for programs to parse. - Alibaba Cloud CLI

Alibaba Cloud CLI writes its help information and error messages for human readers. An AI agent must parse this content, which increases the parsing cost and the number of retries. When you enable AI Mode, the CLI identifies the caller as an AI agent in the User-Agent of each request. The local output of the CLI also changes to a form that is easier for programs to parse.

Overview

AI Mode brings the following changes:

Alibaba Cloud services use this identifier to distinguish agent calls from manual operations for troubleshooting and call statistics.
An agent can parse the output of the CLI directly, which reduces the number of retries.

Note

AI Mode does not change the permissions of an API call or the request parameters.
AI Mode does not guarantee forward compatibility. If your automation workflow uses AI Mode, do not rely on a fixed output structure.

Behavior changes when AI Mode is enabled

The AI Mode capabilities require Alibaba Cloud CLI 3.5.0 or later. When you enable AI Mode, the local output of the CLI changes in ways that include but are not limited to:

The CLI returns help information in a more compact form.
The CLI returns error information in a structured form, with the cause of the failure and the next step.
The CLI validates parameter values locally.
The output contains no color control characters.

When content is presented in a summarized form, the output tells you how to retrieve the complete content.

Manage AI Mode

Manage AI Mode with the aliyun configure ai-mode command group.

View the current configuration

Run the following command to view the current configuration of AI Mode:

aliyun configure ai-mode show

Example output:

{
  "enabled": true,
  "user_agent": "",
  "effective_user_agent": "AlibabaCloud-Agent-Skills",
  "request_user_agent_suffix": "AlibabaCloud-AIMode/enabled AlibabaCloud-Agent-Skills",
  "config_file": "/home/user/.aliyun/ai-mode.json"
}

Field descriptions:

Field	Description
`enabled`	Indicates whether AI Mode is enabled.
`user_agent`	The custom User-Agent skills identifier segment. An empty value means the default value is used.
`effective_user_agent`	The skills identifier segment that takes effect: the custom value, or the default value `AlibabaCloud-Agent-Skills`.
`request_user_agent_suffix`	The complete suffix appended to the User-Agent of the request.
`config_file`	Path to the configuration file.

Enable and disable AI Mode

By command

Run the following commands to enable or disable AI Mode:

# Enable AI Mode
aliyun configure ai-mode enable

# Disable AI Mode
aliyun configure ai-mode disable

By environment variable

The AI Mode status is passed through the following environment variables. You can set these variables to control AI Mode:

Environment variable	Description
`ALIBABA_CLOUD_CLI_AI_MODE`	A value of `1` or `true` enables AI Mode. A value of `0` or `false` disables it.
`ALIBABA_CLOUD_CLI_AI_USER_AGENT`	Complete User-Agent suffix appended when AI Mode is active. Example: `AlibabaCloud-AIMode/enabled AlibabaCloud-Agent-Skills`.

Note

In an agent runtime environment, run export ALIBABA_CLOUD_CLI_AI_MODE=1 to enable AI Mode for the current session. The setting applies to every command in the session. You do not need to append the --cli-ai-mode flag to each command. To persist the configuration, use the configure ai-mode command.

Customize the User-Agent skills identifier segment

The default skills identifier segment is AlibabaCloud-Agent-Skills. To distinguish between different AI agents, customize this value:

# Set a custom skills identifier segment
aliyun configure ai-mode set-user-agent --user-agent "MyAgent/1.0"

# Reset to the default value
aliyun configure ai-mode reset-user-agent

After customization, the User-Agent suffix of the request becomes:

AlibabaCloud-AIMode/enabled MyAgent/1.0

Per-command override

When you make an OpenAPI call, you can use a flag on the command line to override the global AI Mode setting for the current command only:

Flag	Effect
`--cli-ai-mode`	Enables AI Mode for this command, even if AI Mode is disabled globally.
`--no-cli-ai-mode`	Disables AI Mode for this command, even if AI Mode is enabled globally.

If both flags appear in the same command, --no-cli-ai-mode takes precedence.

Examples:

# AI Mode is disabled globally, but this command appends the AI identifier
aliyun ecs DescribeInstances --cli-ai-mode

# AI Mode is enabled globally, but this command does not append the identifier
aliyun ecs DescribeInstances --no-cli-ai-mode

Configuration file

To manually view or back up the AI Mode configuration file, find it at the following path for your operating system:

Operating system	Path
Linux / macOS	`~/.aliyun/ai-mode.json`
Windows	`C:\Users\<USER_NAME>\.aliyun\ai-mode.json`

File format example:

{
  "enabled": true,
  "user_agent": "MyAgent/1.0"
}

Field descriptions:

Field	Type	Description
`enabled`	boolean	Specifies whether to enable AI Mode. Default: `false`.
`user_agent`	string	The custom User-Agent skills identifier segment. If empty, the default value `AlibabaCloud-Agent-Skills` is used.

Note

If the configuration file does not exist, AI Mode is disabled by default. Use the aliyun configure ai-mode command to manage the configuration instead of editing the file manually.

Precedence

AI Mode settings are applied in the following order (highest to lowest):

Command-line flags (--cli-ai-mode / --no-cli-ai-mode)
Environment variable (ALIBABA_CLOUD_CLI_AI_MODE)
Configuration file (ai-mode.json)

When a setting with a higher priority takes effect, the settings with a lower priority are ignored. If both --cli-ai-mode and --no-cli-ai-mode are specified in the same command, --no-cli-ai-mode takes precedence.

Scope

AI Mode takes effect in the following scenarios:

OpenAPI calls: The AI identifier segment is appended to the User-Agent for both RPC and RESTful requests initiated through commands.
Plugin commands: The CLI passes AI Mode status to plugin child processes through ALIBABA_CLOUD_CLI_AI_MODE and ALIBABA_CLOUD_CLI_AI_USER_AGENT environment variables, allowing plugins to append the identifier to their own requests.

Appendix: Subcommand reference

Available subcommands under aliyun configure ai-mode:

Subcommand	Description
`show`	Display the current AI Mode configuration.
`enable`	Enable AI Mode globally.
`disable`	Disable AI Mode globally.
`set-user-agent --user-agent <value>`	Set a custom User-Agent skills identifier segment.
`reset-user-agent`	Reset the skills identifier segment to the default value `AlibabaCloud-Agent-Skills`.
`set-ossutil --ossutil <json>`	Configure ossutil plugin settings (JSON string).
`reset-ossutil`	Clear ossutil plugin settings.