alibabacloud-workbench-cli

Workbench CLI エキスパート

Alibaba Cloud ECS インスタンス（特にパブリック IP アドレスがないインスタンス）を、workbench コマンドラインツールで操作できるように支援します。エージェントのワークフロー向けの主な機能は、ミリ秒単位のリモートコマンド実行（exec）、最大 1GB のファイル転送（upload／download）、ポートフォワーディングです。このスキルでは、インストール → 認証情報の設定 → 実行／転送／フォワーディング → セッション管理 → エラーのトラブルシューティングを扱います。

手順

1. Workbench CLI をインストールする

事前確認：

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

アップグレード：

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

2. 認証情報を設定する

認証情報は、アクセス権限 0600 で ~/.workbench/config.json に保存されます。エージェントは、対話型の workbench config コマンドを使用せず、このファイルを直接書き込んでください。

# 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

モード別の設定ファイルスキーマ：

AK モード：

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

RamRoleArn モード（STS トークンを自動更新）：

{
  "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 エンドポイントが認証情報を返します）：

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

モード	使用する場面
AK（デフォルト）	開発、長期間有効な認証情報
StsToken	一時的なセキュリティ認証情報（AccessKey ＋ STS Token）
RamRoleArn	本番環境、アカウント間アクセス、STS ロール引き受けによる最小権限（トークンを自動更新）
CredentialsCmd	ゼロトラスト／Vault 連携 — 外部コマンドが認証情報の JSON を出力
CredentialsURI	メタデータサービス／サイドカー — HTTP エンドポイントが認証情報の JSON を返します

プロファイル管理（非対話型）：

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. コマンドリファレンス

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

グローバルフラグ：

フラグ	用途	デフォルト
--output / -o	出力形式：`text	json`
--region / -r	Alibaba Cloud のリージョン（例：cn-hangzhou）	インスタンス ID のプレフィックスから自動推定
--profile / -P	特定のプロファイルを使用（アクティブなプロファイルより優先）	現在のアクティブなプロファイル

4. インスタンスを一覧表示する

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（key=value または key、複数回指定可能、AND 条件）、--instance-type（例：ecs.g7.large）、--instance-name（ワイルドカード * に対応）、--image-id、--vpc-id、--zone-id、--vswitch-id、--private-ip（カンマ区切り）、--limit（1～100、デフォルト 50）、--next-token（ページネーション）。

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. リモートコマンドを実行する

組み込みの安全対策：CLI は非対話型の実行ツールであり、永続的なシェルは提供しません。呼び出しごとに分離され、ステートレスに実行されるため、残存したシェルセッションによる意図しない連鎖的な損害を防げます。

エージェントの事前確認要件：破壊的なコマンド（例：rm -rf、shutdown、reboot、mkfs、dd、サービスの停止／再起動、またはデータを削除したりシステムを停止したりするコマンド）を実行する前に、エージェントは実行する操作、対象インスタンス、潜在的な影響を説明し、必ずユーザーに確認してください。ユーザーの明示的な承認なしに、破壊的なコマンドを実行してはいけません。

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 を呼び出すたびに、独立したシェルコンテキストで実行されます。状態（cd、export）は呼び出し間で保持されません。同じコンテキストを必要とするコマンドを連結するには、1 回の呼び出し内で && または ; を使用してください。

JSON 出力スキーマ：

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

6. ファイル転送

組み込みの安全機能：upload コマンドには、上書き保護機能が組み込まれています。リモートの保存先にファイルがすでに存在する場合、CLI は上書き前に確認を求めます。

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

デフォルトの回答は No です。ユーザーが明示的に確認しない場合、アップロードは中止されます。これにより、既存のリモートファイルを誤って上書きすることを防ぎます。

エージェントの事前確認要件：対話的な確認ができない自動化／エージェントのワークフローで upload を使用する場合、エージェントはまず、リモートインスタンス上に対象ファイルが存在するかどうかを確認し（例：workbench exec --command "ls -la <path>"）、ファイルが上書きされる場合はユーザーに知らせる必要があります。

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 の第 2 引数（local-path）は省略可能で、省略した場合は現在のディレクトリがデフォルトになります。

7. セッション管理

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

セッションのライフサイクル：OPEN → RECONNECTING → BROKEN → CLOSED。アイドル状態が 30 分続くと、自動的に CLOSED になります。同一インスタンスに対する複数の操作は、1 つのセッションを共有します（透過的な多重化）。

8. デーモン管理

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

• 自動起動：CLI の初回呼び出し時に起動します。
• 自動終了：最後のセッションが閉じられてから 60 秒後に終了します。
• シングルトン：OS ユーザーごとに 1 つだけ起動します（PID ファイルロック）。
• IPC：Unix ソケット上の JSON-RPC（~/.workbench/run/daemon.sock）。

9. リージョンの推定

CLI はインスタンス ID の 3 文字のプレフィックスからリージョンを自動的に推定します（290 以上のリージョンに対応）。推定できない場合は、--region が必須です。list コマンドでは、常に --region が必須です。

終了コード

コード	定数	発生条件
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 指定時）：

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

RAM 権限

必要な最小限の RAM ポリシー：

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

トラブルシューティング

エラーメッセージのパターン	終了コード	最初に行うこと
InvalidAccessKeyId／認証エラー	4	~/.workbench/config.json の AK/SK を確認してください。workbench config を再実行してください。
profile not found	1	workbench config list でプロファイル名を確認してください。
<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 Permissions の RAM ポリシーをユーザーまたはロールに適用してください。
insecure permissions	2	chmod 600 ~/.workbench/config.json を実行してください。
STS トークンの期限切れ	4	RamRoleArn モードを使用している場合、CLI が自動的に更新します。静的 STS を使用している場合は、トークンを更新してください。