Install and manage Alibaba Cloud CLI plugins | parameter serialization - Alibaba Cloud CLI

Instale plugins de CLI para gestionar productos en la nube desde la línea de comandos. Cada plugin corresponde a un producto, se instala bajo demanda, se actualiza de forma independiente y serializa los parámetros automáticamente.

Requisitos previos

Tiene instalado Alibaba Cloud CLI 3.3.0 o una versión posterior. Para consultar las instrucciones de instalación, consulte Install, update, and uninstall Alibaba Cloud CLI.
Ha configurado las credenciales para Alibaba Cloud CLI. Para obtener instrucciones, consulte Configure and manage credentials.

Inicio rápido

Este ejemplo instala el plugin ecs y consulta las regiones:

# Install a plugin (using the ecs plugin as an example)
aliyun plugin install --name ecs

# Call an API to query the list of regions
aliyun ecs describe-regions --accept-language en-US

Ejecute aliyun ecs --help para listar todos los comandos disponibles. Las siguientes secciones abordan la nomenclatura, la instalación, los parámetros y las funciones avanzadas.

Descripción general de los plugins

Cada plugin encapsula la API de un producto en la nube dentro de un ejecutable independiente. Funciones principales:

Instalación bajo demanda: Instale solo lo que necesite.
Actualizaciones independientes: Se versionan y publican por separado del CLI.
Nomenclatura consistente: Los comandos y parámetros utilizan kebab-case (describe-instances, --accept-language).
Parámetros simplificados: El CLI serializa los parámetros automáticamente; utilice el mismo formato clave-valor sin importar el estilo de la API.
Ayuda integrada: Ejecute --help en cualquier comando para ver los tipos de parámetros, descripciones y requisitos.

Los plugins se almacenan en ~/.aliyun/plugins y se registran en manifest.json.

Convención de nombres de plugins

Los plugins siguen el formato de nombre aliyun-cli-<ProductCode>, donde el código de producto coincide con OpenAPI de Alibaba Cloud:

Nombre	Código de producto	Producto en la nube
`aliyun-cli-ecs`	`ecs`	Elastic Compute Service (ECS)
`aliyun-cli-fc`	`fc`	Function Compute (FC)
`aliyun-cli-rds`	`rds`	ApsaraDB RDS

Puede usar el nombre completo (aliyun-cli-ecs) o el código de producto (ecs). Los nombres no distinguen entre mayúsculas y minúsculas.

Instalación de plugins

Comprobar disponibilidad de plugins

Verifique si un producto en la nube cuenta con un plugin:

Consulta en línea (recomendado): Navegue por categoría, busque por palabra clave y consulte ejemplos de comandos en el CLI Center.

Consulta por línea de comandos: Liste los plugins disponibles o busque por palabra clave:

Liste todos los plugins en el índice remoto:
```
aliyun plugin list-remote
```

Salida de ejemplo:

Total plugins available: 316

Name                                     Latest Version  Preview  Status         Local Version  Description
----                                     --------------  -------  ------         -------------  -----------
aliyun-cli-ecs                           0.1.0           No       Installed      0.1.0          Alibaba Cloud CLI plugin for ECS operations.
aliyun-cli-fc                            0.1.0           No       Installed      0.1.0          Alibaba Cloud CLI plugin for FC 3.0 operations.
aliyun-cli-acc                           0.1.0           No       Not installed  -              Alibaba Cloud CLI plugin for acs operations.

Buscar un plugin

Encuentre qué plugin proporciona un comando específico. Se admite la coincidencia por prefijo.

# Search for plugins containing "ecs"
aliyun plugin search ecs
# Search for commands in the ecs plugin that start with "describe"
aliyun plugin search "ecs describe"

Nota

Los plugins siguen el Versionado Semántico (SemVer):
- Las versiones 0.x.x son experimentales y no garantizan compatibilidad.
- Las versiones 1.0.0+ son estables dentro de la misma versión mayor. Los cambios de versión mayor pueden introducir modificaciones incompatibles.
El índice remoto se almacena en caché durante una hora. Para forzar la actualización, establezca ALIBABA_CLOUD_CLI_PLUGIN_NO_CACHE=true.

Instalar un plugin

aliyun plugin install acepta un plugin mediante --name (por ejemplo, aliyun plugin install --name ecs) o un argumento posicional (por ejemplo, aliyun plugin install ecs). Ambas opciones son equivalentes. La opción --name se agregó en la v3.3.14.

Opción	Descripción
`--name <name>`	Instala un solo plugin por nombre. Disponible desde la v3.3.14. Es mutuamente excluyente con `--names` y `--package`.
`--names <name1> <name2> ...`	Instala uno o más plugins por nombre, separados por espacios. Es mutuamente excluyente con `--name` y `--package`.
`--version <version>`	Especifique la versión a instalar. Solo funciona con `--name`. Si no se especifica, se instala la última versión estable.
`--enable-pre`	Permite la instalación de versiones preliminares.
`--package <path-or-url>`	Instala desde un archivo local (`.zip`, `.tar.gz`, `.tgz`) o una URL que apunte a un archivo comprimido. Es mutuamente excluyente con `--name` y `--names`.
`--source-base <url>`	Utilice una URL de origen de plugin personalizada para este comando. Anula la variable de entorno y la configuración del archivo.

Ejemplos:

# Install a single plugin by name
aliyun plugin install --name ecs

# Install a specific version
aliyun plugin install --name fc --version 1.0.0

# Install multiple plugins at once
aliyun plugin install --names ecs rds vpc

# Install from a local archive file (for offline environments)
aliyun plugin install --package /path/to/ecs-plugin.zip

# Install from a URL
aliyun plugin install --package https://example.com/plugins/ecs-plugin.tar.gz

Compruébelo con aliyun plugin list:

Name                Version             Description
----                -------             -----------
aliyun-cli-ecs      0.1.0               Aliyun CLI plugin for Elastic Compute Service operations.
aliyun-cli-fc       0.1.0               Aliyun CLI plugin for Function Compute 3.0 operations.

Nota

El CLI detecta automáticamente el sistema operativo y la arquitectura (darwin-arm64, linux-amd64) y descarga el paquete correspondiente. En instalaciones por lotes, un fallo no bloquea las demás. Los plugins que requieren una versión más reciente del CLI le solicitarán que actualice.

Consultar detalles del plugin

Ejecute aliyun plugin list para listar los plugins instalados. Para ver los detalles de un plugin específico, ejecute:

aliyun plugin show --name ecs

Salida de ejemplo:

Name:	              aliyun-cli-ecs
Version:	      0.3.0
Product code:	      Ecs
Short description:    Aliyun Ecs Plugin
Description:	      Aliyun CLI plugin for Elastic Compute Service operations.
API default:	      2014-05-26
API supported:	      2014-05-26

Campos:

Campo	Descripción
Name	Nombre completo (por ejemplo, `aliyun-cli-ecs`).
Version	Versión instalada.
Product code	Código de producto (por ejemplo, `ecs`).
Short description	Resumen breve.
Description	Descripción completa.
API default version	Versión predeterminada de la API para los comandos.
API supported versions	Versiones compatibles. Cámbielas con `--api-version`.
Inner	Indica si el plugin es interno.

Uso de plugins

Los comandos de los plugins usan kebab-case. El CLI pasa automáticamente las credenciales, la región y el tiempo de espera del perfil actual. Las opciones globales como --profile y --region se aplican sin configuración adicional.

Formato del comando:

aliyun <plugin-name> <Command> [--parameter-name value ...]

Ejemplos de uso

Consultar la ayuda del plugin

Utilice aliyun <plugin-name> --help o aliyun <plugin-name> <Command> --help. Por ejemplo, liste todos los comandos de ecs:

aliyun ecs --help

Consulte los detalles de los parámetros de un comando:

aliyun ecs describe-regions --help

Salida de ejemplo:

......
  --accept-language         string, Filters the results by language. For more information, see[RFC
                            7231](https://tools.ietf.org/html/rfc7231). Valid values:
                            - zh-CN: Simplified Chinese.
                            - zh-TW: Traditional Chinese.
                            - en-US: English.
                            - ja: Japanese.
                            - fr: French.
                            - de: German.
                            - ko: Korean.
                            Default: en-US
  --instance-charge-type    string, The billing method for the instance. For more information, see https://help.aliyun.
                            com/document_detail/25398.html. Valid values:
                            - PrePaid: Subscription. If you use this method, make sure your account supports balance payments or credit payments.
                            Otherwise, an `InvalidPayMethod` error is reported.
                            - PostPaid: Pay-As-You-Go.
                            - SpotWithPriceLimit: A user-defined maximum price for a spot instance.
                            - SpotAsPriceGo: The system automatically bids for a spot instance at the Pay-As-You-Go price.
                            Default: PostPaid
......

La salida muestra el tipo de cada parámetro, su descripción y si es obligatorio.

Consultar regiones

Consulte las regiones disponibles:

aliyun ecs describe-regions --accept-language en-US

Salida de ejemplo:

{
  "Regions": {
     "Region": [
	{
	   "LocalName": "China (Qingdao)",
	   "RegionEndpoint": "ecs.cn-qingdao.aliyuncs.com",
	   "RegionId": "cn-qingdao"
			},
	{
	   "LocalName": "China (Beijing)",
	   "RegionEndpoint": "ecs.cn-beijing.aliyuncs.com",
	   "RegionId": "cn-beijing"
	},
......

Uso avanzado

Usar parámetros estructurados

Los plugins serializan los parámetros automáticamente. El formato de entrada es el mismo sin importar el estilo subyacente de la API (repeatList, flat o JSON):

Parámetros de matriz: Repita la opción para cada valor (por ejemplo, attribute-name).

aliyun ecs describe-account-attributes\
      --biz-region-id cn-hangzhou\
      --attribute-name max-security-groups\
      --attribute-name instance-network-type

Parámetros de objeto: Utilice pares key=value (por ejemplo, tag).

aliyun ecs describe-instances --biz-region-id cn-hangzhou\
       --tag key=env value=prod

Usar APIs multiversión

Algunos productos tienen varias versiones de API. Ejecute aliyun plugin list; los plugins con soporte multiversión muestran multi-version en su descripción:

Name                Version             Description
----                -------             -----------
aliyun-cli-ecs      0.1.0               Alibaba Cloud CLI plugin for ECS operations.
aliyun-cli-ess      0.1.0               Alibaba Cloud CLI plugin for Auto Scaling operations with multi-version API support.
aliyun-cli-fc       0.1.0               Alibaba Cloud CLI plugin for FC 3.0 operations.

Utilice --api-version para seleccionar una versión específica:

Use la versión predeterminada de la API

aliyun ess describe-scaling-groups --biz-region-id cn-hangzhou

Especifique una versión de la API mediante --api-version

aliyun ess describe-scaling-groups --api-version 2022-02-22 --biz-region-id cn-hangzhou

Liste las versiones de API compatibles
```
aliyun ess list-api-versions 
```

Establezca una versión predeterminada de la API con una variable de entorno para evitar repetir --api-version. Formato: ALIBABA_CLOUD_<PRODUCT_CODE>_API_VERSION (<PRODUCT_CODE> en mayúsculas):

# Add the environment variable and apply it
echo 'export ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22' >> ~/.bashrc
source ~/.bashrc

La opción --api-version tiene prioridad sobre la variable de entorno.

Actualizar y desinstalar plugins

Actualizar un plugin

Actualice un plugin específico:

aliyun plugin update --name ecs

Actualice todos los plugins instalados:

aliyun plugin update

Si ya tiene la versión más reciente, el CLI indicará que no se requiere ninguna actualización. Agregue --enable-pre para versiones preliminares.

Compruébelo con aliyun plugin list.

Desinstalar un plugin

Elimine un plugin:

aliyun plugin uninstall --name ecs

Verifique la eliminación con aliyun plugin list.

Configurar la instalación automática

El CLI puede instalar automáticamente los plugins faltantes cuando un comando los requiere, lo cual es útil para pipelines de CI/CD y entornos multiproducto.

Habilitar la instalación automática

Habilítela mediante comando:

aliyun configure set --auto-plugin-install true

O con una variable de entorno:

echo 'export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true' >> ~/.bashrc
source ~/.bashrc

Compruébelo con aliyun configure get.

Permita la instalación automática de versiones preliminares:

aliyun configure set --auto-plugin-install-enable-pre true

O con una variable de entorno:

echo 'export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL_ENABLE_PRE=true' >> ~/.bashrc
source ~/.bashrc

Directiva de instalación

El comportamiento varía según el entorno de ejecución:

Escenario	Comportamiento
Instalación automática habilitada	Se instala automáticamente y continúa la ejecución.
Terminal interactiva con instalación automática deshabilitada	Solicita confirmación antes de instalar.
Entorno no interactivo (script o pipeline)	Muestra un mensaje pero no realiza la instalación.

Salida de ejemplo para la instalación automática:

# Run a command when the ecs plugin is not installed
aliyun ecs describe-regions --accept-language en-US
# Output of the automatic installation process
Plugin 'aliyun-cli-ecs' is required for command 'ecs describe-regions' but not installed.
Auto-installing plugin 'aliyun-cli-ecs' (including pre-release versions)...
Downloading aliyun-cli-ecs 0.1.0...
Plugin aliyun-cli-ecs 0.1.0 installed successfully!
......

Salida de ejemplo en un entorno interactivo con la instalación automática deshabilitada:

# Run a command when the ecs plugin is not installed
aliyun ecs describe-regions --accept-language en-US
# Output of the interactive installation process
Plugin 'aliyun-cli-ecs' is required for command 'ecs describe-regions' but not installed.
Tip: Run 'aliyun configure set --auto-plugin-install true' to skip this prompt.
Do you want to install it? [Y/n]: y
Installing plugin 'aliyun-cli-ecs' (including pre-release versions)...
Downloading aliyun-cli-ecs 0.1.0...
Plugin aliyun-cli-ecs 0.1.0 installed successfully!
......

Configuración global de plugins

Utilice aliyun configure plugin-settings para establecer un origen de plugin personalizado en redes restringidas o para la gestión centralizada de URLs. La configuración se guarda en ~/.aliyun/plugin-settings.json.

Consultar la configuración actual

Consulte la configuración actual:

aliyun configure plugin-settings show

Establecer un origen de plugin personalizado

Establezca una URL de origen personalizada:

aliyun configure plugin-settings set --source-base https://internal-mirror.example.com/cli-plugins

Verifíquelo:

aliyun configure plugin-settings show

Borrar la configuración personalizada

Borre la configuración personalizada y restaure los valores predeterminados:

aliyun configure plugin-settings clear

Prioridad de la URL de origen

El CLI resuelve la URL de origen en el siguiente orden (la primera coincidencia gana):

La opción --source-base en el comando actual.
La variable de entorno ALIBABA_CLOUD_CLI_PLUGIN_SOURCE_BASE.
El valor source-base en ~/.aliyun/plugin-settings.json.
La URL predeterminada integrada.

Nota

La configuración de los plugins se almacena en ~/.aliyun/plugin-settings.json.
Los subcomandos de plugin-settings pertenecen a aliyun configure, no a aliyun plugin.

Apéndice

Lista de comandos de plugins

Comando	Descripción
`aliyun plugin list`	Lista los plugins instalados.
`aliyun plugin show --name <name>`	Muestra los detalles de un plugin instalado.
`aliyun plugin list-remote`	Lista los plugins disponibles del índice remoto.
`aliyun plugin search <command-name>`	Busca el plugin correspondiente a un comando.
`aliyun plugin install (--name	--names [ ...]	--package ) [--version ] [--enable-pre] [--source-base ]`	Instala uno o más plugins.
`aliyun plugin update [--name <name>] [--enable-pre]`	Actualiza un plugin.
`aliyun plugin uninstall --name <name>`	Desinstala un plugin.
`aliyun configure plugin-settings show`	Muestra la configuración del sistema de plugins.
`aliyun configure plugin-settings set --source-base <url>`	Establece la URL base de origen de plugins.
`aliyun configure plugin-settings clear`	Elimina la URL base de origen personalizada y restaura el valor predeterminado integrado.

Variables de entorno de plugins

Variables de entorno para el comportamiento de los plugins:

Variable de entorno	Descripción
`ALIBABA_CLOUD_CLI_PLUGINS_DIR`	Directorio personalizado de plugins. Valor predeterminado: `~/.aliyun/plugins`.
`ALIBABA_CLOUD_CLI_PLUGIN_NO_CACHE`	Establézcala en `true` para deshabilitar el almacenamiento en caché del índice remoto.
`ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL`	Establézcala en `true` para habilitar la instalación automática.
`ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL_ENABLE_PRE`	Establézcala en `true` para permitir la instalación automática de versiones preliminares.
`ALIBABA_CLOUD_CLI_PLUGIN_SOURCE_BASE`	URL de origen personalizada de plugins. Equivalente a `--source-base` en los comandos `plugin install` y `plugin update`. También se puede configurar mediante `aliyun configure plugin-settings set`.
`ALIBABA_CLOUD_<PRODUCT_CODE>_API_VERSION`	Versión predeterminada de la API para un producto. Ejemplo: `ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22`.
`ALIBABA_CLOUD_CLI_MAX_LINE_LENGTH`	Longitud máxima de línea para la salida de ayuda.

Preguntas frecuentes

Fallo en la instalación: "no stable version available"

El plugin solo tiene versiones preliminares. Agregue --enable-pre:

aliyun plugin install --name <plugin-name> --enable-pre