Skip to content

Latest commit

 

History

History
348 lines (239 loc) · 16.3 KB

usage.md

File metadata and controls

348 lines (239 loc) · 16.3 KB

Commands, output, and automation

Documentation index | 简体中文

Command forms

For RPC APIs, use either the traditional PascalCase operation name or the kebab-case command name:

aliyun <product> <Operation> [--Parameter value ...]
aliyun <product> <operation-name> [--parameter value ...]

aliyun ecs DescribeInstances --RegionId cn-hangzhou
aliyun ecs describe-instances --biz-region-id cn-hangzhou

The two command forms call the same API; only the operation and parameter spelling differs. For example:

# List regions
aliyun ecs DescribeRegions
aliyun ecs describe-regions

# List instances
aliyun ecs DescribeInstances --RegionId cn-hangzhou --PageSize 10
aliyun ecs describe-instances --biz-region-id cn-hangzhou --page-size 10

# Show one instance
aliyun ecs DescribeInstanceAttribute --InstanceId i-1234567890abcdef
aliyun ecs describe-instance-attribute --instance-id i-1234567890abcdef

In practice:

  • PascalCase commands use the original API operation name, such as DescribeInstances, and usually keep the original API parameter names such as --RegionId and --InstanceId.
  • Kebab-case commands use the metadata-derived command name, and parameter names are also exposed in kebab-case where defined by metadata. Use the local command help for the exact flag names. For example, describe-instances uses --biz-region-id, while describe-instance-attribute uses --instance-id.

The subcommand casing decides which engine handles the call: an all-lowercase subcommand is routed to the plugin/runtime engine, while a subcommand containing uppercase letters goes through the built-in OpenAPI path. Do not mix the two spellings in one command — aliyun ecs DescribeInstances --biz-region-id cn-hangzhou fails with an unknown parameter error; pair --RegionId with DescribeInstances and --biz-region-id with describe-instances.

Product-level help follows the same split. Without an installed product plugin, aliyun ecs --help shows the PascalCase command list by default; products that exist only in the bundled metadata show the kebab-case list. One-shot environment variables can switch the product Help style. The forms below affect only that invocation and do not persist in the shell:

# Switch from traditional PascalCase Help to kebab-case Help
ALIBABA_CLOUD_BASELINE_PRODUCT_HELP=true aliyun ecs --help

# Return to traditional PascalCase Help
ALIBABA_CLOUD_BASELINE_PRODUCT_HELP=false aliyun ecs --help

# Switch from installed plugin Help to traditional PascalCase Help
ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true aliyun ecs --help

# Return to installed plugin Help
ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=false aliyun ecs --help

Style-switch hints appear only in human-readable product-level Help. AI mode uses structured Help to identify the active command style, and API-level Help shows only the parameters for the selected command style.

Use the product/operation forms above for normal API calls. For APIs that can only be addressed by a raw method and path, the CLI retains the following RESTful compatibility form; it is not the recommended form for general use:

aliyun cs GET /clusters
aliyun cs POST /clusters --body "$(cat input.json)"
aliyun cs DELETE /clusters/<cluster-id>

Each API supports one API style. Check its OpenAPI documentation or local CLI help when unsure.

Discover commands and parameters

Human-readable help:

aliyun --help
aliyun ecs DescribeInstances --help
aliyun ecs describe-instances --help

Endpoints and unsupported metadata

Product JSON Help exposes product.endpoints entries with regionId (when regional) and endpoint. Query them locally with aliyun ecs --help --cli-output json --cli-query product.endpoints; add --endpoint-type vpc for VPC endpoint selection.

The CLI normally resolves API versions and endpoints from metadata. To call an API not present in the bundled metadata, use --force together with an explicit version and endpoint:

aliyun newproduct SomeAction \
  --version 2025-01-01 \
  --endpoint newproduct.aliyuncs.com \
  --SomeParameter value \
  --force

If the request uses an API or parameter that is not present in the local metadata, the CLI returns unknown api or unknown parameter. Use --force to skip those local checks and continue the call.

--force skips API and parameter metadata checks; it does not bypass server-side authorization or validation.

When --force is used, these options should normally be provided explicitly:

  • --version: the API version. Get the version from the product API documentation. For example, ECS commonly uses 2014-05-26.
  • --endpoint: the product endpoint. Use the endpoint documented for that product.

Use --header X-foo=bar repeatedly to add custom HTTP headers. Use --secure to force HTTPS. --skip-secure-verify disables certificate verification and is not recommended.

Validate without invoking

Use --cli-dry-run before a mutating call:

aliyun ecs run-instances ... --cli-dry-run

Support depends on the API metadata. CLI dry-run validation is not a substitute for reviewing permissions and resource impact.

Filter and format output

Table output

OpenAPI responses are JSON by default. For example, a DescribeInstances response may contain a collection like this:

{
  "PageNumber": 1,
  "TotalCount": 2,
  "PageSize": 10,
  "RequestId": "2B76ECBD-A296-407E-BE17-7E668A609DDA",
  "Instances": {
    "Instance": [
      {
        "InstanceId": "i-12345678912345678123",
        "Status": "Stopped"
      },
      {
        "InstanceId": "i-abcdefghijklmnopqrst",
        "Status": "Running"
      }
    ]
  }
}

Use --output to select the collection and render selected fields as a table:

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

The result is:

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

--output supports the following fields:

  • cols is required. It is a comma-separated list of fields evaluated relative to each row. The field names are also used as the table headers.
  • rows is optional. It is a JMESPath expression that selects the array used as table rows. For nested API responses, it is normally required.
  • num=true is optional and adds a zero-based Num column.

For example:

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

The rows expression must resolve to an array. A missing cols value, an invalid JMESPath expression, or a non-array row result causes the command to fail instead of silently producing an incomplete table.

JMESPath query

Use --cli-query to filter or reshape JSON output:

aliyun ecs describe-instances \
  --cli-query 'Instances.Instance[].{Id:InstanceId,Status:Status}'

Use --quiet to suppress normal output where supported.

Pagination

For pageable APIs, --pager repeatedly calls the API and merges the collection from every response:

aliyun ecs describe-instances --pager

With no additional fields, the CLI uses the common response fields PageNumber, PageSize, TotalCount, and NextToken, and attempts to recognize a nested result array automatically. If the collection cannot be recognized, specify its JMESPath explicitly:

aliyun ecs DescribeInstances \
  --pager path='Instances.Instance[]'

APIs that use non-standard pagination fields can override the mapping:

aliyun <product> <operation> \
  --pager \
  path='Data.Items[]' \
  PageNumber='PageInfo.PageNumber' \
  PageSize='PageInfo.PageSize' \
  TotalCount='PageInfo.TotalCount'

Token-based APIs can specify the token field in the same way:

aliyun <product> <operation> \
  --pager path='Data.Items[]' NextToken='Data.NextToken'

The pager fields are:

Field Purpose
path JMESPath expression selecting the result array to merge
PageNumber Page-number request field and response expression
PageSize Page-size request field and response expression
TotalCount Response expression for the total item count
NextToken Next-token request field and response expression

The final JSON contains the merged collection under path; per-page metadata such as request IDs and page numbers is not preserved. Pagination can issue many requests and retain all merged items in memory, so use it carefully for very large result sets. It cannot be combined with --waiter or --cli-dry-run.

Wait for a state

--waiter repeatedly invokes the same API until a JMESPath expression in the response equals the target value. A typical use case is waiting for an ECS instance to enter the Running state after creation:

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

When the expression matches, the CLI stops polling and prints the final API response. The supported fields are:

  • expr is required. It is the JMESPath expression evaluated against each response.
  • to is required. It is the expected value, compared with the evaluated result as text.
  • timeout is optional. It defaults to 180 seconds; use a value from 1 to 600 seconds for compatibility across command forms.
  • interval is optional. It defaults to 5 seconds; use a value from 2 to 10 seconds for compatibility across command forms.

To override the polling limits:

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

The waiter stops immediately if the API call or JMESPath evaluation fails. If the timeout is reached, the error includes the expression, expected value, and last observed value. --waiter cannot be combined with --pager or --cli-dry-run.

Price estimates

Add --estimate-cost to an OpenAPI command to request a quote from the pricing service:

aliyun ecs CreateDisk --RegionId cn-hangzhou --ZoneId cn-hangzhou-i \
  --DiskCategory cloud_essd --Size 40 --estimate-cost

The CLI requests response version 2 and preserves the server's success, code, message, and requestId fields. The service returns price when a quote is available and omits it otherwise. The CLI does not synthesize missing fields and also accepts an explicit price: null from the service.

Outcome success code price Exit code
Quote obtained true Success Quote object 0
Confirmed cost-irrelevant true PricingNotRequired Omitted 0
Quote unavailable false PricingNotSupported Omitted 3

Business outcomes are written to stdout without a second error document on stderr. --cli-query, table output, and --quiet affect presentation only: exit status is determined from the unfiltered response's top-level success. The CLI sends the language selected by --language, the profile, or the system locale to the service.

During rolling upgrades, the CLI also accepts legacy quote and business-error JSON, preserving the original fields and RequestId. Authentication, parameter validation, and network errors retain their usual error handling.

Safety and non-interactive use

Potentially destructive operations may be subject to CLI safety policy and confirmation. Manage policy with:

aliyun configure safety-policy --help

--yes skips a confirmation prompt for non-interactive use, but does not override a deny policy. Review the exact command and scope before using it in automation.

Safety policy is disabled by default, and confirm is a local CLI confirmation rather than cloud authorization or approval. Use show or list to inspect the effective policy. When ALIBABA_CLOUD_SAFETY_POLICY_ENABLED or ALIBABA_CLOUD_SAFETY_POLICY_RULES is set, the displayed policy includes those environment overrides. The CLI refuses to continue when the policy file or environment rules cannot be fully parsed.

After saving an exact rule, the CLI uses the bundled default API version metadata to identify an alternative command name. If the first matching rule in the configuration file does not apply the same action to that name, the CLI prints the name to stderr. Wildcards, REST paths, plugin command hierarchies, and names that cannot be resolved unambiguously do not trigger a notice. This notice does not add rules or change their matching order.

Command matching rules

Safety policy matches the command name supplied by the caller. It does not automatically match alternative names for the same API. Matching is case-insensitive and supports * for any sequence of characters. It does not expand API aliases or convert between PascalCase and kebab-case. For example, ecs:DeleteInstance matches ECS:deleteinstance, but does not match ecs:delete-instance, even though both command forms invoke the same API. This behavior also applies in AI mode.

Configure each spelling used by your scripts or agents:

aliyun configure safety-policy add --pattern 'ecs:DeleteInstance' --action deny
aliyun configure safety-policy add --pattern 'ecs:delete-instance' --action deny
aliyun configure safety-policy enable

Rules are evaluated in order: the first match wins, and unmatched commands are allowed. A wildcard such as ecs:Delete* can cover both spellings by their shared prefix, but does not identify every API with a destructive effect. REST method/path commands use product:METHOD/path (for example, cs:DELETE/clusters); use cs:DELETE/* to match slash-prefixed DELETE paths. Plugin subcommand hierarchies use : (for example, fc:function:create). Configure API-name, method/path, and plugin forms separately when needed. Cloud authorization remains enforced by the service and RAM permissions.

Built-in extensions (such as saectl, ossutil, acrutil, and spark-submit) also check policy before dispatch, ahead of extension installation, credential resolution, and execution. Their identifiers join positional arguments with :, for example saectl:restore or acrutil:diagnosis:restore; *restore* matches both. Host configuration options are excluded. Non-option tokens following unknown extension options are retained, so use wildcards when a rule needs to cover additional arguments. Invocations without extension arguments and standalone help/--help/-h or version/--version requests are exempt. Other invocations are checked even if they contain --help, so an option value cannot accidentally bypass policy as a help request.

Agent-aware optimization and AI mode

AI mode can be managed globally or per command:

aliyun configure ai-mode --help
aliyun ecs describe-instances --cli-ai-mode

When a supported agent environment is detected, in-process OpenAPI commands automatically enable agent-oriented interaction and execution optimizations. These optimizations currently include stricter metadata-based validation and more structured error output, but the exact behavior may change and is not a stable compatibility contract.

ALIBABA_CLOUD_CLI_AGENT_INTEGRATION controls automatic Agent integration: unset enables the defaults, disabled disables all integrations, all enables all, and a comma-separated list such as ai-mode enables only named integrations. This does not enable safety policy. Detected Agent identities also add a fixed Agent/<name> User-Agent segment independently of the AI-mode integration switch.

Requests made through this automatically enabled mode append the following generic User-Agent marker:

AlibabaCloud-AIMode/enabled

To disable automatic agent mode for one command, use --no-cli-ai-mode:

aliyun ecs describe-instances --no-cli-ai-mode

See MCP proxy, OpenTelemetry, and machine-readable interfaces for the JSON Help contract, Agent error envelope, exit statuses, trace-context propagation, and MCP proxy security behavior.

PascalCase argument edge case

This rule applies only to the traditional PascalCase command form. When a parameter value begins with -, use --name=value so the value is not parsed as another flag:

aliyun ecs SomeOperation --PortRange=-1/-1

Built-in OSS

See the built-in OSS automation guide for JSON/JSONL listing, read-only plans, confirmation, and failure reports.

Next: manage product plugins.