Utilisez les commandes list, connect, exec et upload/download pour interroger les instances ECS, vous connecter sans mot de passe, exécuter des commandes à distance et transférer des fichiers. La sortie JSON structurée et la transmission du code de sortie des commandes facilitent l'intégration dans des scripts et le diagnostic rapide des échecs.
Prérequis
Workbench CLI est installé sur votre ordinateur, et les identifiants ainsi que les autorisations RAM minimales sont configurés. Pour plus d'informations, consultez Installer Workbench CLI et configurer les identifiants.
L'instance ECS cible est une instance Linux à l'état Running, et l'agent Cloud Assistant est installé et en cours d'exécution.
Votre ordinateur peut accéder à
*.aliyuncs.comet au point de terminaison WebSocket backend de Workbench. Les commandesuploadetdownloadnécessitent également que l'instance puisse accéder au point de terminaison interne OSS de la région correspondante.
Workbench CLI prend actuellement en charge la connexion uniquement aux instances Linux. Pour vous connecter à une instance Windows, utilisez Se connecter à une instance avec Workbench.
Paramètres globaux
Les trois paramètres globaux suivants s'appliquent à toutes les sous-commandes workbench.
|
Paramètre |
Valeur par défaut |
Description |
|---|---|---|
|
|
|
Le format de sortie. Valeurs valides : |
|
|
Déduit automatiquement |
L'ID de région Alibaba Cloud, par exemple |
|
|
Le profil actif |
Spécifie le profil d'identifiants à utiliser pour cette commande, en remplaçant le profil actif. Utilisez-le pour basculer entre plusieurs comptes ou ensembles d'identifiants. |
La région est déduite selon l'ordre suivant : mappage du préfixe de l'ID d'instance → recherche des sessions actives dans le daemon → **une erreur vous invitant à spécifier --region manuellement**. Lors de la première utilisation d'une instance, nous vous recommandons d'exécuter d'abord workbench list ecs -r <region> pour confirmer l'ID de l'instance.
Interroger la liste des instances (workbench list ecs)
Utilisez cette commande pour interroger les instances ECS par région, état, tag et autres conditions, afin de localiser rapidement l'ID de l'instance cible. workbench list équivaut par défaut à workbench list ecs. Exemples courants :
# 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
Paramètres :
|
Paramètre |
Obligatoire |
Description |
|---|---|---|
|
|
Oui |
L'ID de région Alibaba Cloud. |
|
|
Non |
Filtre par état. Valeurs valides : |
|
|
Non |
Filtre par tag au format |
|
|
Non |
Filtre par type d'instance, par exemple |
|
|
Non |
Filtre par nom d'instance. Le caractère générique |
|
|
Non |
Filtre par ID d'image. |
|
|
Non |
Filtre par ID de VPC. |
|
|
Non |
Filtre par ID de zone. |
|
|
Non |
Filtre par ID de vSwitch. |
|
|
Non |
Filtre par adresses IP privées. Séparez plusieurs adresses par des virgules. |
|
|
Non |
Le nombre maximal d'instances à renvoyer par page. Valeurs valides : 1 à 100. Par défaut : 50. |
|
|
Non |
Le jeton de pagination obtenu à partir de la réponse précédente, utilisé pour récupérer la page suivante. |
La structure de retour de --output json est la suivante :
{
"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"}
}
]
}
Connexion interactive (workbench connect)
workbench connect ouvre une session PTY interactive et constitue la commande principale de Workbench CLI. Exemples courants :
# 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
Paramètres :
|
Paramètre |
Obligatoire |
Valeur par défaut |
Description |
|---|---|---|---|
|
|
Oui* |
— |
L'ID de l'instance ECS. |
|
|
Non |
Déduit automatiquement |
L'ID de région Alibaba Cloud. Il n'est généralement pas nécessaire de le spécifier. |
|
|
Non |
|
Le nom d'utilisateur de connexion à distance. |
|
|
Non |
|
La méthode d'authentification. Valeurs valides : |
|
|
Non |
|
Le port SSH distant. |
|
|
Non |
|
Force une nouvelle session et n'en réutilise pas une existante. |
|
|
Oui* |
— |
Se connecte directement à un ID de session spécifié (utilisation avancée). |
* Spécifiez soit -i, soit --session-id. Si vous spécifiez les deux, --session-id est prioritaire.
Méthodes d'authentification
|
Méthode d'authentification |
Comportement |
Scénario |
|---|---|---|
|
|
Établit une session directement via le canal de connexion sans mot de passe de Workbench, sans qu'il soit nécessaire de prédéfinir un mot de passe ou une clé sur l'instance. |
Opérations quotidiennes sans surcharge de gestion des clés SSH. |
|
|
Vous invite à saisir le mot de passe de manière interactive après la connexion. La saisie n'est pas affichée. |
Scénarios où la connexion par mot de passe est activée sur l'instance et nécessite une authentification SSH par mot de passe. |
|
|
Vous invite à saisir le chemin du fichier de clé de manière interactive après la connexion (par exemple |
Scénarios où l'équipe exige une connexion basée sur une clé et où l'audit doit permettre de remonter à l'empreinte digitale de la clé. |
Commandes interactives et raccourcis clavier
Une fois dans une session workbench connect, appuyez sur Tab au début d'une ligne pour afficher le panneau de commandes slash :
|
Commande |
Fonction |
|---|---|
|
|
Active le mode de conversation avec l'agent IA intégré à la session (voir la section suivante). |
|
|
Téléverse un fichier local vers l'instance (ouvre un sélecteur de fichiers interactif). |
|
|
Télécharge un fichier depuis l'instance vers l'ordinateur local (ouvre un sélecteur de fichiers interactif). |
|
|
Détache la session (la session reste active en arrière-plan et vous pouvez vous y reconnecter ultérieurement en exécutant |
|
|
Quitte et ferme la session. |
|
|
Efface l'écran. |
|
|
Affiche les informations d'aide. |
Raccourcis clavier courants :
|
Touche |
Fonction |
|---|---|
|
|
Affiche le panneau de commandes slash. |
|
|
Active ou désactive le mode agent IA. |
|
|
Quitte la session (équivalent à |
|
|
Interrompt la commande distante en cours sans déconnecter la session. |
Utiliser l'assistant IA intégré à la session
Au sein d'une session workbench connect, vous pouvez invoquer directement l'assistant IA intégré pour que l'IA effectue des opérations sur l'instance actuelle en langage naturel. Vous pouvez le déclencher de trois manières :
Saisissez
/agentau début d'une ligne et appuyez sur Entrée.Appuyez sur le raccourci clavier
Ctrl+A.Appuyez sur
Tabpour afficher le panneau de commandes slash et sélectionnez/agent.
Une fois en mode agent, l'invite de commande change pour devenir une invite dédiée au mode agent. Saisissez directement du langage naturel après cette invite, et l'agent renvoie les réponses en flux continu. Commandes slash en mode agent :
|
Commande |
Fonction |
|---|---|
|
|
Quitte le mode agent et revient au shell standard (Ctrl+A permet également de quitter). |
|
|
Démarre une nouvelle conversation avec l'agent et efface le contexte. |
|
|
Efface l'écran. |
|
|
Déclenche directement un téléversement ou un téléchargement de fichier en mode agent. |
|
|
Affiche l'aide. |
|
|
Quitte et ferme la session. |
Exemple de conversation typique :
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)
Confirmation Human-in-the-loop (HITL) : Avant que l'agent n'exécute une commande sur l'instance, il affiche la commande à exécuter et attend votre confirmation avec Y/n. Les opérations d'API Cloud (telles que la création d'un snapshot) nécessitent également une confirmation. Il s'agit d'un mécanisme clé pour prévenir les actions involontaires de l'IA. Ne le désactivez pas.
L'agent conserve le contexte de la conversation au sein de la même session. Vous pouvez utiliser /new pour le réinitialiser. Les réponses sont diffusées en flux continu et vous pouvez appuyer sur Ctrl+C pour interrompre la génération en cours.
Cette section explique comment invoquer directement l'assistant IA intégré dans une session connect. Si vous souhaitez qu'un agent dans un outil de programmation IA externe (Wukong ou opencode) appelle des commandes workbench, consultez Exploiter des instances ECS avec Workbench CLI dans des agents IA.
Exécution de commandes à distance (workbench exec)
workbench exec exécute une seule commande sur l'instance et renvoie le résultat. Contrairement au shell persistant de connect, chaque appel exec s'exécute dans un environnement indépendant. Plusieurs appels vers la même instance réutilisent le canal de connexion sous-jacent, ce qui évite toute configuration de connexion répétée. Exemples courants :
# 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
Paramètres :
|
Paramètre |
Obligatoire |
Valeur par défaut |
Description |
|---|---|---|---|
|
|
Oui |
— |
L'ID de l'instance ECS. |
|
|
Oui |
— |
La commande à exécuter. |
|
|
Non |
|
Le délai d'expiration, en secondes. |
Chaque appel exec s'exécute dans un environnement shell indépendant et n'hérite ni du répertoire courant, ni des variables d'environnement, ni de l'état du shell de l'appel précédent. Si vous avez besoin d'une continuité de contexte (par exemple, exécuter cd puis une autre commande), combinez les commandes avec && ou ; dans le même paramètre -c.
La structure de retour de --output json est la suivante :
{
"output": "Filesystem ...\n",
"stderr": "",
"exit_code": 0
}
Dans cette structure, output correspond à la sortie standard de la commande, stderr à l'erreur standard et exit_code au code de sortie de la commande distante (un entier).
Transfert de fichiers (workbench upload / download)
Lorsque vous ne disposez pas d'adresse IP publique ou de canal SCP, utilisez workbench upload / workbench download pour transférer des fichiers. Le processus de téléversement affiche une barre de progression en temps réel.
Exemple de téléversement :
workbench upload ./app.jar /opt/app/app.jar -i i-bp1a2b3c4d5e6f
Exemple de téléchargement :
# 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
Paramètres :
|
Paramètre |
Obligatoire |
Valeur par défaut |
Description |
|---|---|---|---|
|
|
Oui |
— |
L'ID de l'instance ECS. |
Les fichiers sont transférés en étant relayés via OSS, ce qui est totalement transparent pour vous et ne nécessite aucune autorisation OSS ni configuration de bucket. L'instance doit pouvoir accéder au point de terminaison interne OSS de la région correspondante (oss-<region>-internal.aliyuncs.com).
Gestion des sessions (workbench session)
Les sessions sont généralement créées, réutilisées et nettoyées automatiquement par l'interface CLI et ne nécessitent aucune intervention lors d'une utilisation quotidienne. Les commandes de cette section servent au diagnostic et au nettoyage manuel.
Commandes courantes :
# 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
Transitions d'état des sessions :
OPEN: La session est établie et peut être lue et écrite normalement.RECONNECTING: Le WebSocket sous-jacent s'est déconnecté et est en cours de reconnexion.BROKEN: La reconnexion a échoué et la session n'est pas disponible.CLOSED: La session est fermée (fermée par l'utilisateur, expiration du délai ou atteinte de la limite TTL).
Plusieurs opérations connect, exec, upload et download sur la même instance partagent la même session, gérée de manière transparente par le daemon, de sorte que vous n'avez pas à vous soucier de l'ID de session. Un seul terminal (TTY) peut être attaché à la même session à la fois. Si un terminal est déjà attaché, vous pouvez utiliser --new pour créer une nouvelle session, ou fermer d'abord la connexion existante.
Gestion du daemon (workbench daemon)
Workbench CLI s'appuie sur un daemon d'arrière-plan en espace utilisateur pour maintenir la connexion WebSocket et multiplexer les sessions. Le cycle de vie du daemon est entièrement automatique et ne nécessite généralement aucune gestion manuelle.
# View the daemon status
workbench daemon status
# Stop the daemon (closes all sessions)
workbench daemon stop
Démarrage automatique : Le daemon est démarré automatiquement la première fois que vous exécutez une commande
workbench.Arrêt automatique : Le daemon s'arrête automatiquement 60 secondes après la fermeture de la dernière session.
Instance unique : Une seule instance de daemon est autorisée par utilisateur du système d'exploitation (appliquée par un verrou de fichier PID).
Canal IPC : L'interface CLI et le daemon communiquent via
~/.workbench/run/daemon.sock(un socket Unix), en utilisant le protocole JSON-RPC.
Scénarios typiques
Scénario 1 : Déploiement d'application
Téléversez le package de déploiement → exécutez le script de déploiement à distance → vérifiez l'état de santé du service sur l'instance.
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"
Scénario 2 : Exécution groupée de commandes de diagnostic
Utilisez exec --output json pour obtenir des résultats structurés pouvant être analysés ultérieurement par un script ou filtrés avec jq.
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'
Scénario 3 : Se rattacher à une session après détachement
Pour les tâches de longue durée (comme le suivi des journaux ou la compilation), vous pouvez exécuter /detach puis fermer le terminal local. Lorsque vous exécutez à nouveau connect ultérieurement, vous vous rattachez automatiquement à la session d'origine.
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
Codes de sortie
workbench exec transmet le code de sortie de la commande distante : quel que soit le code de sortie renvoyé par la commande distante, l'interface CLI se termine avec le même code de sortie (comportement cohérent avec SSH). Par conséquent, un script peut déterminer si la commande distante a réussi directement à partir du code de sortie de workbench exec.
Par exemple, la commande suivante exécute exit 42 sur l'instance, et l'interface CLI se termine également avec 42 :
workbench exec -i i-bp1a2b3c4d5e6f -c "exit 42"
echo $? # Outputs 42
Lorsqu'une commande échoue pour des raisons telles que des paramètres incorrects, une authentification défaillante, un problème réseau ou une instance inexistante, l'utilisation de --output json affiche les détails de l'erreur au format suivant :
{
"code": 1,
"message": "session resolve: login instance: ... InvalidParameter.InstanceId ..."
}
Dans cette structure, code est un identifiant d'erreur non nul et message est une description d'erreur lisible (qui inclut généralement le code d'erreur et le RequestId de l'API sous-jacente), que vous pouvez utiliser pour localiser le problème.
Dépannage
Symptômes courants et première action à entreprendre :
|
Symptôme / message d'erreur |
Première action |
|---|---|
|
Échec d'authentification / |
Vérifiez si l'ID AccessKey et le secret AccessKey dans |
|
Une erreur indiquant que l'instance n'existe pas / |
Confirmez que l'ID d'instance et la région sont corrects. Vous pouvez exécuter |
|
Échec de la connexion sans mot de passe / |
Par défaut, la connexion sans mot de passe (lorsque |
|
|
Vérifiez si le nom du profil est correct. Exécutez |
|
Délai de connexion dépassé / erreur WebSocket |
Vérifiez si votre ordinateur peut accéder à |
|
La connexion est occupée (la session est déjà attachée par un autre terminal) |
Utilisez |
|
Impossible de se connecter au daemon |
Exécutez |
|
Erreur d'autorisation du fichier de configuration |
Exécutez |
|
Jeton STS expiré |
En mode RamRoleArn, l'interface CLI actualise automatiquement. Si vous utilisez un jeton STS statique, mettez à jour le jeton. |
Commandes de débogage :
# 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
Les journaux du daemon sont enregistrés dans ~/.workbench/log/daemon.log.
Références
Se connecter à une instance avec Workbench CLI : la rubrique parente, qui couvre le positionnement de l'outil et le démarrage rapide.
Installer Workbench CLI et configurer les identifiants : installation de l'interface CLI et configuration des identifiants/autorisations.
Exploiter des instances ECS avec Workbench CLI dans des agents IA : faire appel à un agent pour exécuter des commandes workbench dans Wukong ou opencode.
Installer l'agent Cloud Assistant : Workbench CLI dépend de l'agent Cloud Assistant.