All Products
Search
Document Center

Elastic Compute Service:Create and run commands

Last Updated:May 15, 2026

Run Shell or PowerShell scripts on multiple ECS instances without logging in.

Important

Commands run with the specified username's permissions. Use a non-root user following the principle of least privilege to minimize security risk.

Prerequisites

Ensure the following:

  • Cloud Assistant Agent is installed on your target instances.

  • Target instances are in the Running state with network connectivity.

  • The executing user has read, write, and execute permissions on the relevant files and directories.

Procedure

Console

  1. Go to ECS console - ECS Cloud Assistant.

  2. In the top navigation bar, select the region and resource group. Region

  3. In the upper-right corner of the ECS Cloud Assistant page, click Create/Run Command.

  4. In the Command Information section, configure the following:

    • Command content: Paste or type your script.

      To use dynamic values, enable Use Parameters and add parameters in {{parameter}} format:

      • Custom Parameters: Defined in {{parameter}} format. Assign values manually when running the command.

      • Built-in parameters: Provided by Cloud Assistant and replaced at runtime — for example, {{ACS::RegionId}} (region ID) and {{ACS::InstanceId}} (instance ID).

      #!/bin/bash
      # {{name}} is a custom parameter — assign a value when running.
      echo {{name}}
      
      # {{ACS::RegionId}} is a built-in parameter — no value needed.
      echo {{ACS::RegionId}}
      Note: Base64-encoded command payload limit: 18 KB for Run And Save, 24 KB for Run.
    • Execution Plan: Choose when to run the command.

      • *(Default)* Immediately.

      • Perform Only Dry Run: Validates request parameters, instance environment, and Cloud Assistant Agent status without running the command.

      • Run on Schedule:

        • Run at Fixed Interval: Runs at a fixed interval defined by a rate expression. Must be between 60 seconds and 7 days, and longer than the command timeout.

        • Run on Clock-based Schedule: Uses a cron expression for flexible scheduling.

    • Username: Defaults to root (Linux) or System (Windows).

    • Execution Path: The script's working directory. Defaults to /root (Linux) or C:\Windows\system32 (Windows). To change directory, add a cd command at the start of the script.

    • Timeout: Defaults to 60 seconds. Valid range: 10–86,400 seconds (24 hours).

    • Task Stop Scope: What stops when a task is terminated.

      • Command Process: Stops the script process only.

      • Command Process Tree: Stops the script process and all its child processes.

  5. In the Select Instance or Select Managed Instances section, select the target instances.

    Select up to 100 instances per execution. If an expected instance is missing, verify that Cloud Assistant Agent is installed and the instance is in the Running state.
  6. Click Run and Save or Run to start.

CLI

All examples use aliyun ecs RunCommand. For the full parameter reference, see RunCommand.

  1. Step 1: Encode your script

    RunCommand accepts CommandContent as plaintext or Base64-encoded content. To use Base64 encoding, set ContentEncoding to Base64 and encode your script first:

    Linux / macOS

    # Use -n to avoid encoding the trailing newline
    echo -n "hello world" | base64
    # Output: aGVsbG8gd29ybGQ=

    Windows (PowerShell)

    [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("hello world"))
    # Output: aGVsbG8gd29ybGQ=
  2. Step 2: Run the command

    Run on a single instance

    # The Base64-encoded value of "yum -y update" is "eXVtIC15IHVwZGF0ZQ=="
    aliyun ecs RunCommand --RegionId 'cn-hangzhou' \
      --Type 'RunShellScript' \
      --ContentEncoding 'Base64' \
      --CommandContent 'eXVtIC15IHVwZGF0ZQ==' \
      --InstanceId.1 'i-bp1************de01'

    Run on multiple instances

    Specify multiple instances with --InstanceId.N:

    aliyun ecs RunCommand --RegionId 'cn-hangzhou' \
      --Type 'RunShellScript' \
      --ContentEncoding 'Base64' \
      --CommandContent 'eXVtIC15IHVwZGF0ZQ==' \
      --InstanceId.1 'i-bp1************de01' \
      --InstanceId.2 'i-bp1************de02' \
      --InstanceId.3 'i-bp1************de03'

    Run on a schedule (cron)

    # Run at 12:00 PM every day in 2024, Asia/Shanghai time zone
    aliyun ecs RunCommand --RegionId 'cn-hangzhou' \
      --Type 'RunShellScript' \
      --ContentEncoding 'Base64' \
      --CommandContent 'eXVtIC15IHVwZGF0ZQ==' \
      --RepeatMode 'Period' \
      --Frequency '0 0 12 * * ? 2024 Asia/Shanghai' \
      --InstanceId.1 'i-bp1************de01'
  3. Step 3: Check the results

    RunCommand returns an InvokeId. Query execution results with:

    # Replace <invoke_id> with your InvokeId
    aliyun ecs DescribeInvocationResults --RegionId 'cn-hangzhou' --InvokeId '<invoke_id>'

    See DescribeInvocationResults for parameter details.

    In the response, check:

    • Output: the script's standard output (STDOUT)

    • ErrorInfo and ErrorMsg: error details

Limitations

  • Maximum instances per execution: 100. To raise this limit, see Manage quotas.

  • Maximum saved commands per region: 500 by default. Commands run without saving do not count against this quota. To raise this limit, see Manage quotas.

  • Some advanced features require specific Cloud Assistant Agent versions. See Features and versions.

  • Base64-encoded command payload: max 18 KB (Run And Save) or 24 KB (Run).

  • Timeout range: 10–86,400 seconds. Fixed-interval schedules must be at least 60 seconds and exceed the command timeout.

Apply in production

Use idempotence for CLI/SDK calls

Set ClientToken to ensure idempotence when calling RunCommand via CLI or SDK. This prevents duplicate executions from network retries.

Set up monitoring and alerts

Subscribe to Cloud Assistant events through EventBridge or CloudMonitor to get notified on command failures. Early detection reduces time to resolution.

FAQ

How do I check the Cloud Assistant Agent version on an instance?

Check from the console or by logging in to the instance. See Install Cloud Assistant Agent.

For a fixed-interval scheduled task, does it run immediately after creation?

No. The first run occurs after the first interval elapses. For example, a task created at 10:00 with a 10-minute interval first runs at 10:10.

My command failed. How do I troubleshoot it?

Check the Output log on the execution results page — error messages are usually there. Then:

  1. Verify the executing user has read, write, and execute permissions on the relevant files and directories.

  2. Test the script by running it manually on the instance.

  3. Confirm the instance is in the Running state with network connectivity.

  4. If the error is ClientNeedUpgrade, upgrade the Cloud Assistant Agent.

See Check execution results and troubleshoot common issues for a full troubleshooting reference.

Next steps