Connect to an instance by using Workbench CLI - Elastic Compute Service

What Is Workbench CLI

Important

Workbench CLI currently supports connecting only to Linux instances (over the SSH protocol). It does not support connecting to Windows instances. To connect to a Windows instance, see Connect to an instance by using Workbench.

Workbench CLI (the command is workbench) is a command-line tool for connecting to instances that is provided by Alibaba Cloud ECS. It is suitable for the following users:

Human users: When no public IP address is assigned to an instance, use the command line to perform interactive login, remote command execution, and file upload and download, as an alternative to a direct SSH connection.
AI agents: With structured JSON output (--output json) and exit code passthrough, AI programming tools (such as Wukong and opencode) can call the workbench command directly to manage ECS instances, without additional adaptation.

The core capabilities of Workbench CLI are as follows:

Interactive login: workbench connect opens a PTY session and supports three authentication methods: passwordless, password, and key.
Remote command execution: workbench exec runs a single command on an instance and returns the result in text or JSON format.
File transfer: workbench upload and workbench download transfer files between your computer and an instance by using OSS as a relay.
Session and daemon management: workbench session and workbench daemon are used for diagnostics and manual cleanup. No intervention is required for daily use.
In-session AI agent assistant: In an interactive connect session, press Tab or Ctrl+A to invoke the AI assistant and use natural language to have the AI run commands on the instance.

Comparison with Other ECS Connection Methods

Alibaba Cloud ECS provides three connection methods that are based on Workbench or Session Manager and do not require a public IP address. The following table compares these methods.

Capability	Workbench (web)	Workbench CLI	Session Manager CLI (ali-instance-cli)
Interaction	Browser GUI	Local command line	Local command line
Public IP address required	No	No	No
Supported instance operating systems	Linux and Windows	Linux only (over the SSH protocol)	Linux and Windows
Remote commands and file transfer	Manual operations in the web terminal	Native commands: exec, upload, and download	Terminal sessions only; requires additional scripting
Designed for AI agents	No	Yes (structured JSON output and exit code passthrough)	No
Typical scenarios	Ad hoc troubleshooting and Windows desktop access	Daily O&M scripts and AI programming assistants	Existing scripts that require only terminal sessions

Recommendations for selecting a method:

If you need a graphical interface or need to connect to a Windows instance, use Connect to an instance by using Workbench.
If you need to operate Linux instances from the command line or in AI programming tools, use Workbench CLI.
If you have existing ali-instance-cli scripts and need only terminal sessions, you can continue to use them. For more information, see Connect to an instance by using ali-instance-cli.

Limits

Instance operating system: Only Linux instances are supported (over the SSH protocol). Windows instances are not supported.
Cloud Assistant agent: The target instance must have the Cloud Assistant agent installed and running properly. ECS instances that were created from official public images after December 1, 2017 have the Cloud Assistant agent preinstalled by default. Otherwise, you must install it manually.
Security group rules: On the first connection, the CLI automatically adds an internal security group rule for the instance (TCP port 22, with 100.104.0.0/16 authorized). If your account does not have security group permissions, add the rule manually in the ECS console.
Network connectivity: Your computer must be able to access *.aliyuncs.com and the Workbench backend WebSocket endpoint. The upload and download commands require the instance to be able to access the internal OSS endpoint of the corresponding region.

Important

Windows instances are not currently supported by Workbench CLI. Do not use workbench connect for Windows instances.

Quick Start

Complete your first connection in 5 minutes by performing the following three steps. For detailed instructions on installation, credentials, and commands, see Install Workbench CLI and configure credentials and Manage ECS instances by using Workbench CLI.

Step 1: Install Workbench CLI

Select an installation command based on the operating system of your computer. The installation script automatically detects the architecture (amd64 or arm64) and installs to the default system path.

Linux or macOS

curl -fsSL https://workbench-cli.oss-cn-hangzhou.aliyuncs.com/install.sh | bash

Windows

irm https://workbench-cli.oss-cn-hangzhou.aliyuncs.com/install.ps1 | iex

Step 2: Configure an AccessKey Pair

Run the following command and enter the AccessKey ID and AccessKey secret as prompted.

workbench config

After the configuration is complete, the credentials are saved in ~/.workbench/config.json, and the file permissions are automatically set to 0600 (read and write for the current user only). In production environments, we recommend that you use RAM role credentials instead of a static AccessKey pair. For more information about the configuration method, see Install Workbench CLI and configure credentials.

Step 3: Connect to an Instance

Run the following command to connect to the target instance. Replace i-bp1a2b3c4d5e6f with your instance ID.

workbench connect -i i-bp1a2b3c4d5e6f

The region is automatically inferred from the instance ID prefix, so you usually do not need to specify it manually by using -r. After you enter the interactive shell, press Tab to invoke the slash command panel (such as /upload, /download, and /agent), and press Ctrl+D to exit the session.

Command Overview

Command	Description
`workbench list ecs`	Queries the list of ECS instances by region, status, or tag.
`workbench connect`	Opens an interactive PTY session to connect to an instance. Supports passwordless, password, and key authentication.
`workbench exec`	Runs a single command on an instance and returns the result. Supports text and JSON output.
`workbench upload` / `workbench download`	Uploads or downloads files between your computer and an instance by using OSS as a relay.
`workbench session`	Queries and manually closes sessions. No intervention is required for daily use.
`workbench daemon`	Views or stops the background daemon. It starts automatically on the first call and exits automatically after 60 seconds of idle time.
`workbench config`	Configures credentials. Supports five modes (AK, StsToken, RamRoleArn, CredentialsCmd, and CredentialsURI) and multiple profiles.
`workbench upgrade`	Upgrades to the latest version or a specified version.
`workbench version`	Prints the current version number, commit, and build date.

All of the preceding commands support the --output json, --region, and --profile global parameters. For the complete parameters, examples, and JSON output structure of each command, see Manage ECS instances by using Workbench CLI.

References

Install Workbench CLI and configure credentials: Install the CLI on Linux, macOS, and Windows, and configure the five credential modes (AK, StsToken, RamRoleArn, CredentialsCmd, and CredentialsURI) and the minimum RAM permission policy.
Manage ECS instances by using Workbench CLI: The parameters, examples, typical scenarios, and troubleshooting for the list, connect, exec, upload, download, session, and daemon commands.
Operate ECS instances by using Workbench CLI in AI agents: How to load the Workbench CLI skill in AI programming tools such as Wukong and opencode, as well as typical conversation scenarios and security recommendations.