/alibabacloud-workbench-cli

name: alibabacloud-workbench-cli
description: |
  Agent-native CLI for managing ECS instances without public IPs, primarily for single-instance operations. It supports millisecond-level remote command execution, large file transfers up to 1GB, and TCP port forwarding. It offers four authentication modes: AK, RamRoleArn, CredentialsCmd, and CredentialsURI. Use it to run commands, deploy code, view logs, check processes, transfer files, set up port forwarding, or query and filter ECS instance lists.
license: Apache-2.0
metadata:
  domain: cloud-infrastructure
compatibility: Requires workbench CLI binary installed. Cross-platform Linux/macOS (amd64/arm64), Windows (amd64). Network access to *.aliyuncs.com and Workbench backend WebSocket endpoints required.
allowed-tools: Bash

Workbench CLI Expert

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.

Instructions

1. Install the Workbench CLI

**Pre-check:**

workbench version     # Should print version, commit, build date

**Linux / macOS:**

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

**Windows (PowerShell):**

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

**Upgrade:**

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

2. Configure credentials

Credentials are stored in `~/.workbench/config.json` with `0600` permissions. As an Agent, write this file directly instead of using the interactive `workbench config` command.

# Create config directory
mkdir -p ~/.workbench

# Write config file (example: AK mode)
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:

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

RamRoleArn mode (auto-refreshes STS tokens):

{
  "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):

{
  "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):**

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)

3. Command reference

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` | `text` | | `--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 |

4. List instances

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`