Elastic Compute Service:Manage ECS instances by using Workbench CLI

Prerequisites

• Workbench CLI is installed on your computer, and credentials and the minimum RAM permissions are configured. For more information, see Install Workbench CLI and configure credentials.

• The target ECS instance is a Linux instance in the Running state, and the Cloud Assistant agent is installed and running.

• Your computer can access *.aliyuncs.com and the Workbench backend WebSocket endpoint. The upload and download commands also require the instance to be able to access the OSS internal endpoint of the corresponding region.

Global parameters

The following three global parameters apply to all workbench subcommands.

The region is inferred in the following order: instance ID prefix mapping → lookup of active sessions in the daemon → an error that prompts you to specify --region manually. When you use an instance for the first time, we recommend that you run workbench list ecs -r <region> first to confirm the instance ID.

Query the instance list (workbench list ecs)

Use this command to query ECS instances by region, status, tag, and other conditions, so that you can quickly locate the target instance ID. workbench list is equivalent to workbench list ecs by default. Common examples:

# Query all instances in a specified region
workbench list ecs -r cn-hangzhou

# Query only running instances
workbench list ecs -r cn-hangzhou --status Running

# Filter by tag (multiple --tag options use AND semantics)
workbench list ecs -r cn-hangzhou --tag env=prod --tag app=web

# Filter by instance type, name, VPC, and other conditions
workbench list ecs -r cn-hangzhou --instance-type ecs.g7.large --instance-name "web-*"

# Output JSON for consumption by scripts or AI agents
workbench list ecs -r cn-hangzhou --output json

Parameters:

The return structure of --output json is as follows:

{
  "instances": [
    {
      "instance_id": "i-bp1xxxxx",
      "instance_name": "web-prod-01",
      "instance_type": "ecs.g7.large",
      "region_id": "cn-hangzhou",
      "status": "Running",
      "private_ip": "172.16.0.10",
      "public_ip": "",
      "os_type": "linux",
      "image_id": "aliyun_3_x64_20G_alibase_20230727.vhd",
      "tags": {"env": "prod"}
    }
  ]
}

Interactive connection (workbench connect)

workbench connect opens an interactive PTY session and is the core command of Workbench CLI. Common examples:

# Default no authentication (Workbench passwordless logon)
workbench connect -i i-bp1a2b3c4d5e6f

# Password authentication (enter the password interactively; input is not echoed)
workbench connect -i i-bp1a2b3c4d5e6f --auth-type password

# Certificate authentication (enter the key file path interactively, such as ~/.ssh/id_rsa)
workbench connect -i i-bp1a2b3c4d5e6f --auth-type certificate

# Specify the logon user and port
workbench connect -i i-bp1a2b3c4d5e6f -u admin -p 2222

# Force a new session (do not reuse an existing session)
workbench connect -i i-bp1a2b3c4d5e6f --new

Parameters:

Agent> Show the processes with the highest CPU usage
  ┌─ Running command ──────────
  │ ps aux --sort=-%cpu | head -10
  └────────────────────────
  Waiting for confirmation (Y/n): y
  [Executed]
  ... (the agent continues its analysis and provides conclusions)

Remote command execution (workbench exec)

workbench exec runs a single command on the instance and returns the result. Unlike the persistent shell of connect, each exec call runs in an independent environment. Multiple calls to the same instance reuse the underlying connection channel, so no repeated connection setup is needed. Common examples:

# Run a command
workbench exec -i i-bp1a2b3c4d5e6f -c "df -h"

# Combine commands: cd + environment variable + run
workbench exec -i i-bp1a2b3c4d5e6f -c "cd /opt/app && ./deploy.sh"

# Set a timeout
workbench exec -i i-bp1a2b3c4d5e6f -c "sleep 30" --timeout 10

# JSON output for consumption by scripts or AI agents
workbench exec -i i-bp1a2b3c4d5e6f -c "df -h" --output json

Parameters:

The return structure of --output json is as follows:

{
  "output": "Filesystem ...\n",
  "stderr": "",
  "exit_code": 0
}

In this structure, output is the standard output of the command, stderr is the standard error, and exit_code is the exit code of the remote command (an integer).

File transfer (workbench upload / download)

When you do not have a public IP address or an SCP channel, use workbench upload / workbench download to transfer files. The upload process displays a real-time progress bar.

Upload example:

workbench upload ./app.jar /opt/app/app.jar -i i-bp1a2b3c4d5e6f

Download example:

# Download to the current directory
workbench download /var/log/app.log ./ -i i-bp1a2b3c4d5e6f

# Download and rename
workbench download /var/log/app.log ./local-copy.log -i i-bp1a2b3c4d5e6f

Parameters:

Session management (workbench session)

Common commands:

# View all active sessions
workbench session list
workbench session list --output json

# Close a specified session
workbench session close <session-id>

# Close all sessions
workbench session close --all

Session state transitions:

• OPEN: The session is established and can be read from and written to normally.

• RECONNECTING: The underlying WebSocket has disconnected and is reconnecting.

• BROKEN: Reconnection failed and the session is unavailable.

• CLOSED: The session is closed (closed by the user, timed out, or reached the TTL limit).

Multiple connect, exec, upload, and download operations on the same instance share the same session, which is handled transparently by the daemon, so you do not need to be concerned about the session ID. Only one terminal (TTY) can attach to the same session at a time. If a terminal is already attached, you can use --new to create a new session, or close the existing connection first.

Daemon management (workbench daemon)

Workbench CLI relies on a user-space background daemon to hold the WebSocket connection and multiplex sessions. The lifecycle of the daemon is fully automatic and usually requires no manual management.

# View the daemon status
workbench daemon status

# Stop the daemon (closes all sessions)
workbench daemon stop

• Automatic startup: The daemon is started automatically the first time you run any workbench command.

• Automatic exit: The daemon exits automatically 60 seconds after the last session is closed.

• Single instance: Only one daemon instance is allowed per operating system user (enforced by a PID file lock).

• IPC channel: The CLI and the daemon communicate through ~/.workbench/run/daemon.sock (a Unix socket), using the JSON-RPC protocol.

Typical scenarios

workbench upload ./app-2.0.tar.gz /opt/deploy/ -i i-bp1a2b3c4d5e6f
workbench exec -i i-bp1a2b3c4d5e6f -c "cd /opt/deploy && tar xzf app-2.0.tar.gz && ./deploy.sh"
workbench exec -i i-bp1a2b3c4d5e6f -c "curl -s http://localhost:8080/health"

workbench exec -i i-bp1a2b3c4d5e6f -c "df -h && free -m" --output json | jq '.output'
workbench exec -i i-bp1a2b3c4d5e6f -c "systemctl status nginx" --output json | jq '.exit_code'

workbench connect -i i-bp1a2b3c4d5e6f
# Run tail -f or a long-running task in the session
# Then enter /detach to detach

# Reattach to the original session later
workbench connect -i i-bp1a2b3c4d5e6f

Exit codes

workbench exec passes through the exit code of the remote command: whatever exit code the remote command returns, the CLI exits with the same exit code (consistent with SSH behavior). Therefore, a script can determine whether the remote command succeeded directly from the exit code of workbench exec.

For example, the following command runs exit 42 on the instance, and the CLI also exits with 42:

workbench exec -i i-bp1a2b3c4d5e6f -c "exit 42"
echo $?   # Outputs 42

When a command fails due to reasons such as parameters, authentication, network, or a nonexistent instance, using --output json outputs the error details in the following format:

{
  "code": 1,
  "message": "session resolve: login instance: ... InvalidParameter.InstanceId ..."
}

In this structure, code is a non-zero error identifier, and message is a readable error description (which usually includes the error code and RequestId of the underlying API), which you can use to locate the issue.

Troubleshooting

Common symptoms and the first action to take:

Debugging commands:

# View the daemon status
workbench daemon status

# JSON error output for easy parsing by scripts
workbench exec -i i-bp1a2b3c4d5e6f -c "echo test" --output json

The daemon logs are saved in ~/.workbench/log/daemon.log.

References

• Connect to an instance by using Workbench CLI: the parent topic, which covers the tool's positioning and quick start.

• Install Workbench CLI and configure credentials: CLI installation and credential/permission configuration.

• Operate ECS instances by using Workbench CLI in AI agents: have an agent call workbench commands in Wukong or opencode.

• Install the Cloud Assistant agent: Workbench CLI depends on the Cloud Assistant agent.