alibabacloud-workbench-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Workbench CLI Expert

Workbench CLI 使用专家

Help users operate Alibaba Cloud ECS instances — especially those without public IP addresses — using the

workbench

command-line tool. Core capabilities for Agent workflows: millisecond-level remote command execution (

exec

), file transfer up to 1GB (

upload

download

), and port forwarding. This skill covers: install → configure credentials → exec/transfer/forward → manage sessions → troubleshoot errors.

帮助用户使用

workbench

命令行工具操作阿里云ECS实例——尤其是无公网IP的实例。适用于Agent工作流的核心功能：毫秒级远程命令执行（

exec

）、最大1GB的文件传输（

upload

download

）以及端口转发。本技能涵盖：安装 → 配置凭证 → 执行/传输/转发 → 会话管理 → 故障排查。

Instructions

使用说明

1. Install the Workbench CLI

1. 安装Workbench CLI

Pre-check:

bash

workbench version     # Should print version, commit, build date

Linux / macOS:

bash

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

Windows (PowerShell):

powershell

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

Upgrade:

bash

workbench upgrade                        # Upgrade to latest
workbench upgrade --version 0.2.0        # Upgrade to specific version

预检查：

bash

workbench version     # 应输出版本、提交记录、构建日期

Linux / macOS 系统：

bash

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

Windows（PowerShell）：

powershell

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

升级：

bash

workbench upgrade                        # 升级至最新版本
workbench upgrade --version 0.2.0        # 升级至指定版本

2. Configure credentials

2. 配置凭证

Credentials are stored in

~/.workbench/config.json

with

permissions. As an Agent, write this file directly instead of using the interactive

workbench config

command.

bash

undefined

凭证存储在

~/.workbench/config.json

文件中，权限设置为

。作为Agent，直接写入该文件即可，无需使用交互式的

workbench config

命令。

bash

undefined

Create config directory

创建配置目录

mkdir -p ~/.workbench

Write config file (example: AK mode)

写入配置文件（示例：AK模式）

cat > ~/.workbench/config.json << 'EOF' { "current": "default", "profiles": { "default": { "mode": "AK", "access_key_id": "<AccessKeyID>", "access_key_secret": "<AccessKeySecret>" } } } EOF

Set secure permissions

设置安全权限

chmod 600 ~/.workbench/config.json


**Config file schema by mode:**

AK mode:
```json
{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "AK",
      "access_key_id": "LTAI...",
      "access_key_secret": "..."
    }
  }
}

RamRoleArn mode (auto-refreshes STS tokens):

json

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "RamRoleArn",
      "access_key_id": "LTAI...",
      "access_key_secret": "...",
      "ram_role_arn": "acs:ram::123456789:role/WorkbenchRole",
      "role_session_name": "workbench-session"
    }
  }
}

CredentialsURI mode (HTTP endpoint returns credentials):

json

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "CredentialsURI",
      "credentials_uri": "http://localhost:8080/credentials"
    }
  }
}

Mode	When to use
AK (default)	Development, long-lived credentials
StsToken	Temporary security credentials (AccessKey + STS Token)
RamRoleArn	Production, cross-account, least-privilege via STS role assumption (auto-refreshes tokens)
CredentialsCmd	Zero-trust / Vault integration — external command outputs credential JSON
CredentialsURI	Metadata service / sidecar — HTTP endpoint returns credential JSON

Profile management (non-interactive):

bash

workbench config list                     # List all profiles (* marks active)
workbench config switch --profile prod    # Switch active profile
workbench config get                      # Show current profile details (JSON)
workbench config get --profile prod       # Show specific profile details
workbench config delete --profile old     # Delete a profile (cannot delete active)

chmod 600 ~/.workbench/config.json


**各模式对应的配置文件结构：**

AK模式：
```json
{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "AK",
      "access_key_id": "LTAI...",
      "access_key_secret": "..."
    }
  }
}

RamRoleArn模式（自动刷新STS令牌）：

json

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "RamRoleArn",
      "access_key_id": "LTAI...",
      "access_key_secret": "...",
      "ram_role_arn": "acs:ram::123456789:role/WorkbenchRole",
      "role_session_name": "workbench-session"
    }
  }
}

CredentialsURI模式（HTTP端点返回凭证）：

json

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "CredentialsURI",
      "credentials_uri": "http://localhost:8080/credentials"
    }
  }
}

模式	使用场景
AK（默认）	开发环境、长期有效凭证
StsToken	临时安全凭证（AccessKey + STS令牌）
RamRoleArn	生产环境、跨账号、通过STS角色授权实现最小权限（自动刷新令牌）
CredentialsCmd	零信任/Vault集成——外部命令输出凭证JSON
CredentialsURI	元数据服务/边车代理——HTTP端点返回凭证JSON

配置文件管理（非交互式）：

bash

workbench config list                     # 列出所有配置文件（*标记当前活跃配置）
workbench config switch --profile prod    # 切换活跃配置文件
workbench config get                      # 显示当前配置文件详情（JSON格式）
workbench config get --profile prod       # 显示指定配置文件详情
workbench config delete --profile old     # 删除配置文件（无法删除当前活跃配置）

3. Command reference

3. 命令参考

workbench
├── exec             # Execute remote command (non-interactive, millisecond-level)
├── upload           # Upload local file to instance (up to 1GB, via OSS relay)
├── download         # Download file from instance (up to 1GB, via OSS relay)
├── list             # List ECS instances
├── session          # Session management (list / close)
├── daemon           # Daemon lifecycle (start / status / stop)
├── config           # Credential configuration & profile management
│   ├── set          # Set a single config field
│   ├── list         # List all profiles
│   ├── switch       # Switch active profile
│   ├── get          # Show profile details
│   └── delete       # Delete a profile
├── upgrade          # Self-update
└── version          # Print version info

Global flags:

Flag	Purpose	Default
`--output` / `-o`	Output format: `text	json`
`--region` / `-r`	Alibaba Cloud region (e.g., `cn-hangzhou` )	auto-inferred from instance ID prefix
`--profile` / `-P`	Use a specific profile (overrides active profile)	current active profile

workbench
├── exec             # 执行远程命令（非交互式，毫秒级响应）
├── upload           # 上传本地文件至实例（最大1GB，通过OSS中转）
├── download         # 从实例下载文件（最大1GB，通过OSS中转）
├── list             # 列出ECS实例
├── session          # 会话管理（列出/关闭）
├── daemon           # 守护进程生命周期（启动/状态/停止）
├── config           # 凭证配置与配置文件管理
│   ├── set          # 设置单个配置字段
│   ├── list         # 列出所有配置文件
│   ├── switch       # 切换活跃配置文件
│   ├── get          # 显示配置文件详情
│   └── delete       # 删除配置文件
├── upgrade          # 自动更新
└── version          # 输出版本信息

全局参数：

参数	用途	默认值
`--output` / `-o`	输出格式：`text	json`
`--region` / `-r`	阿里云地域（例如： `cn-hangzhou` ）	从实例ID前缀自动推断
`--profile` / `-P`	使用指定配置文件（覆盖当前活跃配置）	当前活跃配置文件

4. List instances

4. 列出实例

bash

workbench list ecs --region cn-hangzhou
workbench list ecs --region cn-hangzhou --status Running
workbench list ecs --region cn-hangzhou --tag env=prod --tag team=infra
workbench list ecs --region cn-hangzhou --instance-type ecs.g7.large
workbench list ecs --region cn-hangzhou --instance-name my-instance
workbench list ecs --region cn-hangzhou --image-id ubuntu_22_04_x64_20G_alibase_20230907.vhd
workbench list ecs --region cn-hangzhou --output json

--region

is required for

list ecs

. Filters:

--status

(Running|Stopped|Starting|Stopping),

--tag

(key=value or key, repeatable, AND logic),

--instance-type

(e.g. ecs.g7.large),

--instance-name

(supports wildcards

--image-id

--vpc-id

--zone-id

--vswitch-id

--private-ip

(comma-separated),

--limit

(1-100, default 50),

--next-token

(pagination).

JSON output schema:

json

[{
  "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": "ubuntu_22_04_x64_20G_alibase_20230907.vhd",
  "tags": {"env": "prod"}
}]

bash

workbench list ecs --region cn-hangzhou
workbench list ecs --region cn-hangzhou --status Running
workbench list ecs --region cn-hangzhou --tag env=prod --tag team=infra
workbench list ecs --region cn-hangzhou --instance-type ecs.g7.large
workbench list ecs --region cn-hangzhou --instance-name my-instance
workbench list ecs --region cn-hangzhou --image-id ubuntu_22_04_x64_20G_alibase_20230907.vhd
workbench list ecs --region cn-hangzhou --output json

执行

list ecs

时必须指定

--region

。筛选条件：

--status

（Running|Stopped|Starting|Stopping）、

--tag

（键=值或仅键，可重复，逻辑为与）、

--instance-type

（例如ecs.g7.large）、

--instance-name

（支持通配符

）、

--image-id

、

--vpc-id

、

--zone-id

、

--vswitch-id

、

--private-ip

（逗号分隔）、

--limit

（1-100，默认50）、

--next-token

（分页）。

JSON输出结构：

json

[{
  "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": "ubuntu_22_04_x64_20G_alibase_20230907.vhd",
  "tags": {"env": "prod"}
}]

5. Remote command execution

5. 远程命令执行

Built-in safety: The CLI is a non-interactive executor — it does NOT provide a persistent shell. Each invocation is isolated and stateless, which prevents accidental cascading damage from lingering shell sessions.

Agent pre-check requirement: Before executing destructive commands (e.g.,

rm -rf

shutdown

reboot

mkfs

dd

, service stop/restart, or any command that deletes data or halts the system), the Agent MUST confirm with the user by describing the intended action, the target instance, and the potential impact. Do NOT execute destructive commands without explicit user approval.

bash

workbench exec --instance-id i-bp1xxxxx --command "df -h"
workbench exec --instance-id i-bp1xxxxx --command "sleep 30" --timeout 10
workbench exec --instance-id i-bp1xxxxx --command "df -h" --output json

Flag	Required	Description	Default
`--instance-id` / `-i`	Yes	ECS instance ID	—
`--command` / `-c`	Yes	Command to execute	—
`--timeout`	No	Timeout in seconds	`30`

Important: Each

exec

invocation runs in an independent shell context. State (cd, export) is NOT preserved between calls. Use

&&

to chain commands that need shared context in a single invocation.

JSON output schema:

json

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

内置安全机制：该CLI为非交互式执行器——不提供持久化Shell。每次调用都是独立且无状态的，可避免因残留Shell会话导致的意外连锁损坏。

Agent预检查要求：在执行破坏性命令（例如

rm -rf

、

shutdown

、

reboot

、

mkfs

、

dd

、服务启停，或任何删除数据、终止系统的命令）前，Agent必须向用户确认，说明操作意图、目标实例及潜在影响。未经用户明确批准，不得执行破坏性命令。

bash

workbench exec --instance-id i-bp1xxxxx --command "df -h"
workbench exec --instance-id i-bp1xxxxx --command "sleep 30" --timeout 10
workbench exec --instance-id i-bp1xxxxx --command "df -h" --output json

参数	是否必填	描述	默认值
`--instance-id` / `-i`	是	ECS实例ID	—
`--command` / `-c`	是	要执行的命令	—
`--timeout`	否	超时时间（秒）	`30`

重要提示：每次

exec

调用都在独立的Shell环境中运行。状态（如cd、export）不会在多次调用间保留。如需共享上下文的命令，需在单次调用中使用

&&

或

串联。

JSON输出结构：

json

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

6. File transfer

6. 文件传输

Built-in safety: The

upload

command has a built-in overwrite protection. When the remote destination file already exists, the CLI prompts for confirmation before overwriting:

Remote file "/root/id.txt" already exists (728 B, modified Jul 27 10:42). Overwrite? [y/N]

The default answer is No — if the user does not explicitly confirm, the upload is aborted. This prevents accidental overwriting of existing remote files.

Agent pre-check requirement: When using

upload

in automated/Agent workflows where interactive confirmation is not possible, the Agent MUST first check whether the target file exists on the remote instance (e.g., via

workbench exec --command "ls -la <path>"

) and inform the user if a file will be overwritten.

bash

workbench upload ./app.jar /opt/app/app.jar --instance-id i-bp1xxxxx
workbench download /var/log/app.log ./ --instance-id i-bp1xxxxx
workbench download /var/log/app.log /tmp/local-copy.log --instance-id i-bp1xxxxx

Transfer goes through OSS as intermediary — transparent to the user, no OSS configuration needed.

download

second arg (local-path) is optional, defaults to current directory.

内置安全机制：

upload

命令内置覆盖保护。当远程目标文件已存在时，CLI会提示确认后再覆盖：

Remote file "/root/id.txt" already exists (728 B, modified Jul 27 10:42). Overwrite? [y/N]

默认回答为否——若用户未明确确认，上传会中止。这可防止意外覆盖远程已有文件。

Agent预检查要求：在自动化/Agent工作流中使用

upload

且无法进行交互式确认时，Agent必须先检查远程实例上是否存在目标文件（例如通过

workbench exec --command "ls -la <path>"

），并告知用户是否会覆盖文件。

bash

workbench upload ./app.jar /opt/app/app.jar --instance-id i-bp1xxxxx
workbench download /var/log/app.log ./ --instance-id i-bp1xxxxx
workbench download /var/log/app.log /tmp/local-copy.log --instance-id i-bp1xxxxx

传输通过OSS作为中转——对用户透明，无需配置OSS。

download

的第二个参数（本地路径）为可选，默认值为当前目录。

7. Session management

7. 会话管理

bash

workbench session list
workbench session list --output json
workbench session close <session-id>
workbench session close --all

Session lifecycle: OPEN → RECONNECTING → BROKEN → CLOSED. Idle timeout 30min → auto CLOSED. Multiple operations on same instance share one session (transparent multiplexing).

bash

workbench session list
workbench session list --output json
workbench session close <session-id>
workbench session close --all

会话生命周期：OPEN → RECONNECTING → BROKEN → CLOSED。闲置超时30分钟后自动转为CLOSED。同一实例上的多个操作共享一个会话（透明多路复用）。

8. Daemon management

8. 守护进程管理

bash

workbench daemon start      # Manual start (usually not needed)
workbench daemon status
workbench daemon stop       # Closes all sessions

Auto-start: Spawned on first CLI invocation.
Auto-exit: 60 seconds after last session closes.
Singleton: One per OS user (PID file lock).
IPC: JSON-RPC over Unix socket (
```
~/.workbench/run/daemon.sock
```
).

bash

workbench daemon start      # 手动启动（通常无需操作）
workbench daemon status
workbench daemon stop       # 关闭所有会话

自动启动：首次调用CLI时自动启动。
自动退出：最后一个会话关闭后60秒自动退出。
单例模式：每个操作系统用户仅运行一个实例（通过PID文件锁实现）。
IPC：通过Unix套接字（
```
~/.workbench/run/daemon.sock
```
）进行JSON-RPC通信。

9. Region inference

9. 地域推断

The CLI auto-infers region from the instance ID 3-character prefix (covers 290+ regions). If inference fails,

--region

is required. For

list

command,

--region

is always required.

CLI可通过实例ID的3字符前缀自动推断地域（支持290+个地域）。若推断失败，则必须指定

--region

。对于

list

命令，始终需要指定

--region

。

Exit Codes

退出码


ExitSuccess
ExitGeneral
ExitArgument
ExitSessionNotFound
ExitAuth
ExitNetwork
ExitDaemonUnreach
ExitSessionBusy
exec

Code	Constant	Trigger
0	`ExitSuccess`	Successful execution
1	`ExitGeneral`	Unclassified runtime error (includes instance not found, API errors, etc.)
2	`ExitArgument`	Missing, malformed, or invalid flag value
3	`ExitSessionNotFound`	Session ID invalid or expired
4	`ExitAuth`	Authentication or authorization failed
5	`ExitNetwork`	Network timeout, WebSocket exception
6	`ExitDaemonUnreach`	Local daemon not running or socket invalid
7	`ExitSessionBusy`	Session attached by another TTY
N	(exec only)	`exec` transparently passes through the remote command's exit code

Error JSON output (on failure with

--output json

json

{
  "code": 1,
  "message": "InvalidParameter.InstanceId: the specified instance does not exist"
}


ExitSuccess
ExitGeneral
ExitArgument
ExitSessionNotFound
ExitAuth
ExitNetwork
ExitDaemonUnreach
ExitSessionBusy
exec

代码	常量	触发场景
0	`ExitSuccess`	执行成功
1	`ExitGeneral`	未分类运行时错误（包括实例未找到、API错误等）
2	`ExitArgument`	参数缺失、格式错误或无效
3	`ExitSessionNotFound`	会话ID无效或已过期
4	`ExitAuth`	认证或授权失败
5	`ExitNetwork`	网络超时、WebSocket异常
6	`ExitDaemonUnreach`	本地守护进程未运行或套接字无效
7	`ExitSessionBusy`	会话已被其他TTY连接
N	(仅exec命令)	`exec` 会透传远程命令的退出码

错误信息JSON输出（失败时使用

--output json

）：

json

{
  "code": 1,
  "message": "InvalidParameter.InstanceId: the specified instance does not exist"
}

RAM Permissions

RAM权限

Minimum RAM policy required:

json

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs-workbench:LoginECSInstance",
        "ecs-workbench:ChatMessages"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecs:DescribeInstances",
        "ecs:DescribeCloudAssistantStatus",
        "ecs:StartTerminalSession"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "ram:CreateServiceLinkedRole",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "ram:ServiceName": "workbench.ecs.aliyuncs.com"
        }
      }
    }
  ]
}

Restrict to specific instances: replace

"Resource": "*"

in each statement with the corresponding format:

ecs-workbench:LoginECSInstance :

acs:ecs:<region>:<account-id>:ecs/<instance-id>

ecs actions:

acs:ecs:<region>:<account-id>:instance/<instance-id>

所需最小RAM策略：

json

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs-workbench:LoginECSInstance",
        "ecs-workbench:ChatMessages"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecs:DescribeInstances",
        "ecs:DescribeCloudAssistantStatus",
        "ecs:StartTerminalSession"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "ram:CreateServiceLinkedRole",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "ram:ServiceName": "workbench.ecs.aliyuncs.com"
        }
      }
    }
  ]
}

如需限制到特定实例：将每个语句中的

"Resource": "*"

替换为对应格式：

ecs-workbench:LoginECSInstance :

acs:ecs:<region>:<account-id>:ecs/<instance-id>

ecs操作：

acs:ecs:<region>:<account-id>:instance/<instance-id>

Troubleshooting

故障排查

Error message pattern	Exit Code	First Action
`InvalidAccessKeyId` / authentication errors	4	Verify AK/SK in `~/.workbench/config.json` . Re-run `workbench config` .
`profile not found`	1	Check profile name with `workbench config list` .
`not found in <region>` / instance not found	1	Verify instance ID and region. Use `workbench list --region <region>` to confirm.
Network timeout / WebSocket errors	5	Check network connectivity to `*.aliyuncs.com` . Verify security group rules.
Session busy / attach errors	7	Another terminal is attached. Close it first, or use `workbench session close <id>` .
`cannot start daemon` / socket errors	6	Run `workbench daemon status` . If stopped, any command will auto-restart it.
Permission denied (RAM)	4	Attach the RAM policy from `## RAM Permissions` to the user or role.
`insecure permissions`	2	Run `chmod 600 ~/.workbench/config.json` .
STS token expired	4	If using `RamRoleArn` mode, the CLI auto-refreshes. If using static STS, update the token.

错误消息模式	退出码	首要操作
`InvalidAccessKeyId` / 认证错误	4	验证 `~/.workbench/config.json` 中的AK/SK。重新执行 `workbench config` 。
`profile not found`	1	使用 `workbench config list` 检查配置文件名称。
`not found in <region>` / 实例未找到	1	验证实例ID和地域。使用 `workbench list --region <region>` 确认。
网络超时 / WebSocket错误	5	检查与 `*.aliyuncs.com` 的网络连通性。验证安全组规则。
会话繁忙 / 连接错误	7	已有终端连接该会话。先关闭它，或使用 `workbench session close <id>` 。
`cannot start daemon` / 套接字错误	6	执行 `workbench daemon status` 。若已停止，任何命令都会自动重启它。
权限拒绝（RAM）	4	为用户或角色附加 `## RAM权限` 中的RAM策略。
`insecure permissions`	2	执行 `chmod 600 ~/.workbench/config.json` 。
STS令牌过期	4	若使用 `RamRoleArn` 模式，CLI会自动刷新。若使用静态STS令牌，需更新令牌。