Alibaba Cloud CLI AI Mode appends an AI identifier to the User-Agent of API requests for server-side identification of AI agent requests, auditing, and analytics. It can be managed through commands or configuration files. - Alibaba Cloud CLI

AI Mode, available since Alibaba Cloud CLI 3.3.3, appends an AI identifier to the User-Agent of every API request so servers can distinguish AI agent traffic from manual requests.

Overview

When enabled, the CLI appends the following segment to the User-Agent of each API request:

AlibabaCloud-AIMode/enabled AlibabaCloud-Agent-Skills

Where:

AlibabaCloud-AIMode/enabled: fixed prefix indicating AI Mode is active.
AlibabaCloud-Agent-Skills: default skills identifier, customizable.

The AI identifier lets you:

Distinguish AI agent requests from manual operations.
Enable server-side auditing, rate limiting, and analytics by agent identity.

Note

AI Mode only modifies the User-Agent header. It does not change API behavior or permissions.

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:

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`	Custom skills identifier. Empty means the default is used.
`effective_user_agent`	Effective skills identifier: the custom value if set, otherwise `AlibabaCloud-Agent-Skills`.
`request_user_agent_suffix`	Complete suffix appended to the User-Agent.
`config_file`	Path to the configuration file.

Enable and disable AI Mode

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

Customize the skills identifier segment

The default skills identifier is AlibabaCloud-Agent-Skills. To differentiate between 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 becomes:

AlibabaCloud-AIMode/enabled MyAgent/1.0

Per-command override

When making an OpenAPI call, you can use a command-line flag 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 disabled globally.
`--no-cli-ai-mode`	Disables AI Mode for this command, even if 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

Environment variables

The CLI exposes AI Mode status to plugin child processes through the following environment variables:

Environment variable	Description
`ALIBABA_CLOUD_CLI_AI_MODE`	Set to `1` when AI Mode is active.
`ALIBABA_CLOUD_CLI_AI_USER_AGENT`	Complete User-Agent suffix appended when AI Mode is active. Example: `AlibabaCloud-AIMode/enabled AlibabaCloud-Agent-Skills`.

Note

The CLI injects these variables automatically when starting a plugin child process. To control AI Mode, use the configure ai-mode command or the --cli-ai-mode flag.

Configuration file

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

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	Custom skills identifier. If empty, defaults to `AlibabaCloud-Agent-Skills`.

Note

If the configuration file does not exist, AI Mode is disabled. Use the aliyun configure ai-mode command 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)
Configuration file (ai-mode.json)

Command-line flags override configuration file settings. If both --cli-ai-mode and --no-cli-ai-mode appear in the same command, --no-cli-ai-mode wins.

Scope

The AI identifier applies in the following scenarios:

OpenAPI calls: The AI identifier 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 skills identifier.
`reset-user-agent`	Reset the skills identifier to `AlibabaCloud-Agent-Skills`.
`set-ossutil --ossutil <json>`	Configure ossutil plugin settings (JSON string).
`reset-ossutil`	Clear ossutil plugin settings.