Utiliser le CLI

Installez le CLI Clowld Space, connectez-vous et gérez les espaces de travail, les tâches, les agents et les runtimes depuis le terminal.

Le CLI Clowld Space sert à la fois à connecter des runtimes locaux et à gérer, depuis le terminal, les espaces de travail, les tâches, les agents et les automatisations. Cette page présente les parcours courants ; les options prises en charge par la version installée sont toujours définies par le --help de chaque commande.

Installation

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/sooodasama/clowld-space/main/scripts/install.sh | bash

Si Homebrew est installé, vous pouvez aussi exécuter :

brew install clowld-ai/tap/clowld

Windows PowerShell

irm https://raw.githubusercontent.com/sooodasama/clowld-space/main/scripts/install.ps1 | iex

Vérifiez l'installation :

clowld version

Première connexion

Se connecter à Clowld Space Cloud :

clowld setup

Se connecter à une instance auto-hébergée :

clowld setup self-host \
  --server-url https://api.example.com \
  --app-url https://app.example.com

setup enregistre l'adresse du serveur, ouvre un navigateur pour finaliser la connexion et démarre le daemon. Une fois l'opération terminée, vérifiez :

clowld auth status
clowld daemon status

Si vous devez seulement vous reconnecter sans écraser le reste de la configuration, exécutez clowld login. Sur une machine sans navigateur, créez d'abord un jeton d'accès personnel dans les paramètres web, puis saisissez-le avec :

clowld login --token

La commande vous invite à coller le jeton dans le terminal, ce qui évite que sa valeur complète n'apparaisse dans l'historique du shell.

Choisir un espace de travail

Listez les espaces de travail et changez celui par défaut :

clowld workspace list
clowld workspace switch <slug>

Les commandes suivantes utilisent cet espace de travail. Une commande isolée peut le remplacer avec --workspace-id, ou vous pouvez définir CLOWLD_WORKSPACE_ID.

Inviter des membres :

clowld workspace member invite teammate@example.com
clowld workspace member invite admin@example.com --role admin

Opérations courantes sur les tâches

# Consulter et rechercher
clowld issue list
clowld issue get CS-123
clowld issue search "échec de connexion"

# Créer et mettre à jour
clowld issue create --title "Corriger l'échec de connexion"
clowld issue status CS-123 in_progress
clowld issue assign CS-123 --to "Backend Agent"

# Commentaires et exécutions
clowld issue comment list CS-123
clowld issue comment add CS-123 --content "Vérifiez d'abord les tests de régression"
clowld issue comment update <comment-id> --expected-revision 2 --content "Vérifiez les tests de régression et les notes de version"
clowld issue runs CS-123

Lisez les descriptions ou commentaires longs depuis stdin pour ne pas avoir à gérer les retours à la ligne et les guillemets :

clowld issue create --title "Notes de mise à niveau" --description-stdin < notes.md
clowld issue comment add CS-123 --content-stdin < review.md
clowld issue comment update <comment-id> --expected-revision 2 --content-file revised-review.md

Afficher les messages d'une exécution, ou l'arrêter :

clowld issue run-messages <task-id> --issue CS-123
clowld issue cancel-task <task-id> --issue CS-123

Agents et skills

clowld agent list
clowld agent get <agent-id>
clowld agent create --help
clowld agent update <agent-id> --help

clowld skill list
clowld skill get <skill-id>
clowld skill import --url <skill-url>
clowld agent skills add <agent-id> --skill-ids <skill-id>

Lorsqu'un import rencontre un skill du même nom, le comportement par défaut est de s'arrêter sans modifier le contenu existant. Choisissez selon votre intention :

clowld skill import --url <skill-url> --on-conflict overwrite
clowld skill import --url <skill-url> --on-conflict rename
clowld skill import --url <skill-url> --on-conflict skip

overwrite n'est autorisé que pour le créateur du skill et conserve l'ID d'origine ainsi que les liaisons avec les agents.

Daemon et runtimes

clowld daemon start
clowld daemon stop
clowld daemon restart
clowld daemon status --output json
clowld daemon logs --follow

clowld runtime list
clowld runtime rename <runtime-id> "Office Mac"
clowld runtime usage <runtime-id>
clowld runtime activity <runtime-id>

La suppression d'un runtime auquel des agents actifs sont encore liés est refusée par défaut. clowld runtime delete <id> --cascade dissocie ces agents, préserve leur configuration et leur historique, et annule leurs exécutions actives.

Consultez Daemon et runtimes pour son fonctionnement et les profils personnalisés.

Vue d'ensemble des commandes

Commande	Rôle
`issue`	Créer, mettre à jour, assigner et rechercher des tâches ; gérer les commentaires, les abonnés, les étiquettes, les propriétés et les exécutions
`topic`	Gérer les topics et leurs ressources
`label`, `property`	Gérer les étiquettes et les propriétés personnalisées de l'espace de travail
`agent`, `skill`, `squad`	Gérer les agents, les skills et les squads
`autopilot`	Gérer les automatisations, les déclencheurs et l'historique des exécutions
`workspace`	Créer, consulter et changer d'espace de travail, et inviter des membres
`repo`	Gérer les dépôts de l'espace de travail et les extraire localement
`daemon`, `runtime`	Démarrer et arrêter le daemon local ; consulter et gérer les runtimes
`attachment`	Envoyer ou télécharger des pièces jointes
`user profile`	Consulter ou mettre à jour le profil de l'utilisateur actuel
`auth`, `login`, `setup`	Se connecter, vérifier l'état de l'authentification et initialiser une connexion
`config`	Consulter ou modifier la configuration locale du profil CLI actuel
`update`, `version`	Mettre à jour le CLI ou afficher la version

clowld chat lit la session de messagerie externe qu'un agent traite actuellement ; elle sert surtout aux agents des intégrations de messagerie et n'est pas une commande générale pour parcourir n'importe quelle discussion de l'espace de travail.

ID et formats de sortie

Les tâches utilisent des clés comme CS-123 ou des UUID complets ; les préfixes courts d'UUID ne sont pas acceptés.

Pour les autres ressources, les commandes list affichent généralement des ID courts copiables et prennent en charge --full-id pour obtenir l'UUID complet. Lorsqu'un ID court est ambigu, le CLI demande davantage de caractères ou l'UUID complet. Les ID courts d'exécution exigent aussi --issue pour identifier la tâche à laquelle ils appartiennent.

De nombreuses commandes prennent en charge une sortie structurée :

clowld issue list --output json
clowld agent list --output json

Les scripts doivent utiliser la sortie JSON plutôt que d'analyser les tableaux destinés au terminal. Les formats de sortie et les options de pagination pris en charge par chaque commande sont définis par clowld <command> --help.

Profils et configuration

La configuration par défaut se trouve dans ~/.clowld-space/cli/config.json. Utilisez --profile <name> pour isoler un ensemble distinct d'adresse de serveur, de jeton, d'espace de travail par défaut et d'état du daemon :

clowld setup self-host --profile staging \
  --server-url https://api.staging.example.com \
  --app-url https://app.staging.example.com

clowld issue list --profile staging

Les profils nommés se trouvent dans ~/.clowld-space/cli/profiles/<name>/config.json. Inspectez les valeurs actuelles :

clowld config show
clowld config show --profile staging

Ne définissez pas CLOWLD_DAEMON_PORT dans le shell hôte, le service Compose ou le point d'entrée du conteneur qui démarre un daemon. Le daemon hôte déduit son port de contrôle de santé de --profile et injecte lui-même cette variable dans les exécutions d'agent. Supprimez complètement la variable des anciens environnements de démarrage : sinon, les versions 0.4.22 et 0.4.23 prennent ce shell pour une exécution gérée et refusent la connexion. Les versions plus récentes permettent à la connexion humaine protégée et à daemon status de se rétablir lorsque le port est le seul signal d'exécution, mais les commandes API ordinaires et celles qui résolvent un profil restent volontairement bloquées (fail-closed) tant que la variable n'est pas supprimée.

Lorsque le CLI tourne au sein d'une exécution d'agent gérée par le daemon, il ne charge ni ne modifie ces fichiers de profil qui appartiennent à l'utilisateur humain. Les commandes de l'API Clowld Space s'authentifient avec l'identifiant limité à l'exécution que le daemon injecte. config show et config set utilisent un état privé, local à l'exécution ; les commandes humaines ou locales comme login, logout, setup, workspace switch, les modifications de chemin des profils de runtime locaux, daemon start / stop / restart, daemon logs et daemon probe-runtimes sont indisponibles. Dans ce contexte, auth status n'affiche aucun élément de jeton.

daemon status et daemon disk-usage restent disponibles pour qu'un agent puisse inspecter le runtime qui l'héberge, dans les limites de ce runtime : status interroge le port de contrôle de santé injecté par le daemon, et disk-usage analyse la racine des répertoires de travail injectée par le daemon. Aucune des deux n'accepte --profile ; disk-usage refuse aussi --all-profiles et --workspaces-root, et sa colonne STATUS reste vide, car la renseigner exigerait le jeton enregistré de l'utilisateur humain. Utilisez du et df pour tout ce qui sort de ce périmètre.

Cela protège la résolution implicite des profils du CLI Clowld Space tout en préservant les variables HOME et XDG habituelles qu'utilisent les outils des autres fournisseurs. Ce n'est pas une frontière du système de fichiers au niveau de l'OS : des processus qui tournent sous le même utilisateur système peuvent toujours ouvrir un chemin connu explicitement. Utilisez un utilisateur dédié, un conteneur, une VM ou une isolation équivalente lorsque cette garantie plus forte est nécessaire.

Les fichiers de configuration du CLI contiennent des jetons qui permettent d'accéder à Clowld Space en votre nom. Ne les commitez pas dans un dépôt, ne les envoyez pas dans des journaux et ne les partagez avec personne.

Référence des commandes

Les tableaux ci-dessous couvrent toutes les commandes de premier niveau actuelles, regroupées comme le CLI lui-même les regroupe. Toutes les commandes acceptent les options globales --server-url, --workspace-id, --profile et --debug. --output est déclarée commande par commande, et le format par défaut varie : les commandes list affichent par défaut un tableau, tandis que les commandes get et create renvoient le plus souvent du JSON. Les options complètes sont définies par clowld <command> --help.

Core

Commande	Sous-commande	Rôle	Options principales
`issue`	`list`	Lister les tâches	`--status`, `--priority`, `--assignee`, `--topic`, `--metadata` (répétable), `--property` (répétable, `"Name=Value"` ; `__none__` correspond à une valeur non définie), `--limit`, `--offset`, `--sort` (y compris `property:<name-or-id>`), `--full-id`, `--resolve-properties` (JSON uniquement ; lignes avec les noms de propriété, d'option et de membre à côté des ID enregistrés)
	`get <id>`	Afficher une tâche	`--resolve-properties` (JSON uniquement ; lignes avec les noms de propriété, d'option et de membre à côté des ID enregistrés)
	`create`	Créer une tâche	`--title` (obligatoire), `--description` / `--description-stdin` / `--description-file`, `--status`, `--priority`, `--assignee`, `--parent`, `--stage`, `--topic`, `--start-date`, `--due-date`, `--attachment` (répétable)
	`update <id>`	Mettre à jour les champs d'une tâche	Mêmes champs que `create`, plus `--position`, `--no-start`
	`assign <id>`	Assigner ou désassigner	`--to` (correspondance approximative sur le nom parmi les membres, les agents et les squads), `--to-id`, `--unassign`, `--no-start`
	`status <id> <status>`	Changer le statut	`--no-start`
	`reorder <id>`	Déplacer au sein d'une colonne
	`search <query>`	Rechercher des tâches	`--limit`, `--include-closed`
	`children <id>`	Lister les sous-tâches regroupées par étape
	`pull-requests <id>`	Lister les PR associées
	`comment list/add/delete/resolve/unresolve`	Gérer les commentaires	`add` : `--content` / `--content-stdin` / `--content-file`, `--parent`, `--attachment` ; `list` : `--since`, `--thread`, `--tail`
	`subscriber list/add/remove <issue-id>`	Gérer les abonnés	`--user`, `--user-id` (par défaut, l'utilisateur actuel)
	`label list/add/remove <issue-id>`	Gérer les étiquettes d'une tâche
	`metadata list/get/set/delete <issue-id>`	Gérer les métadonnées clé-valeur au niveau de la tâche
	`property list/set/unset <issue-id>`	Définir les valeurs des propriétés personnalisées	`set` : `--name`, `--value` (`actor` / `multi_actor` acceptent un nom de membre, un e-mail ou un ID)
	`runs <issue-id>`	Afficher l'historique des exécutions	`--full-id`
	`run-messages <task-id>`	Afficher les messages d'une exécution	`--since`, `--issue`
	`usage <issue-id>`	Afficher la consommation de tokens agrégée
	`rerun <id>`	Remettre en file une exécution pour l'assigné actuel
	`cancel-task <task-id>`	Annuler une exécution en cours ou en file d'attente	`--issue`
`topic`	`list/get/create/update/delete`	Gérer les topics
	`status <id> <status>`	Changer le statut d'un topic
	`resource list/add/update/remove`	Gérer les ressources d'un topic	`--type`, `--url`, `--local-path`, `--daemon-id`, `--execution-mode` (`in_place` / `worktree` pour un répertoire local)
`label`	`list/get/create/update/delete`	Gérer les étiquettes de l'espace de travail	`list` : `--resource-type` (`issue` ou `skill`), `--full-id` ; `create` : `--name`, `--color`, `--resource-type` (`issue` ou `skill`), `--description`
`property`	`list/get/create/update/archive/unarchive`	Gérer les propriétés personnalisées de l'espace de travail	`create` : `--name`, `--type` (`text`, `number`, `select`, `multi_select`, `date`, `checkbox`, `url`, `actor`, `multi_actor`), `--option` (répétable, types select uniquement) ; `list` : `--include-archived` ; le type ne peut plus être modifié après la création
`agent`	`list/get/create/update/archive/restore`	Gérer les agents	`--name`, `--runtime-id` (obligatoire pour `create`), `--instructions`, `--conversation-starters`, `--model`, `--thinking-level`, `--mcp-config`, `--permission-mode`, `--max-concurrent-tasks`
	`copy <agent-id>`	Copier dans un nouvel agent ; l'original reste intact	`--name` (par défaut, le nom d'origine suivi de `(copy)`), `--runtime-id` (copier vers un autre runtime exige aussi `--model`), `--no-skills` ; la configuration secrète comme `custom_env`, `mcp_config` et `runtime_config` n'est pas copiée — fournissez-la à nouveau avec les mêmes options que pour `create`
	`tasks <id>`	Afficher les exécutions d'un agent
	`avatar <id>`	Envoyer un avatar
	`env get/set <agent-id>`	Lire et écrire les variables d'environnement personnalisées (propriétaires et administrateurs uniquement)
	`skills list/set/add <agent-id>`	Gérer les skills rattachés	`--skill-ids` (`set` remplace toute la liste, `add` ajoute à la suite)
	`mcp list/add/enable/disable/remove <agent-id>`	Assigner des serveurs MCP de l'espace de travail à cet agent	Récupérez l'ID du serveur avec `workspace mcp list`. Une entrée de la bibliothèque n'a aucun effet tant qu'elle n'est pas ajoutée ici ; `disable` cesse de l'envoyer sans supprimer l'assignation
`autopilot`	`list/get/create/update/delete`	Gérer les automatisations	`create` : `--title`, `--agent`, `--mode` (tous obligatoires), `--topic`, `--subscriber` (répétable)
	`trigger <id>`	Déclencher une exécution manuellement
	`runs <id>`	Afficher l'historique des exécutions
	`trigger-add/trigger-update/trigger-delete/trigger-rotate-url`	Gérer les déclencheurs de planification et webhook
`workspace`	`list/get/create/update/switch`	Gérer les espaces de travail ; `switch` définit l'espace de travail par défaut du profil actuel
	`mcp list/add/update/remove`	Gérer la bibliothèque de serveurs MCP de l'espace de travail	Les écritures sont réservées aux propriétaires et administrateurs. Un serveur ajouté ici n'est assigné à aucun agent — attribuez-le à un agent avec `clowld agent mcp add`. `list` n'affiche que les noms et les transports ; l'entrée enregistrée est en écriture seule et n'est jamais renvoyée. `--server-config-file` / `--server-config-stdin` gardent les jetons hors de l'historique du shell
	`member list/invite <email>`	Consulter les membres, envoyer des invitations	`invite` : `--role` (member ou admin, member par défaut)
`repo`	`list/add/remove/checkout`	Gérer les dépôts de l'espace de travail et les extraire localement	`--url` (répétable) ; `checkout` : `--ref`
`skill`	`list/get/create/update/delete`	Gérer les skills
	`import`	Importer un skill depuis une URL ou un fichier local	`--url` / `--file`, `--on-conflict` (`fail`, `overwrite`, `rename`, `skip` ; `fail` par défaut)
	`search <query>`	Rechercher des skills
	`files list/upsert/delete <skill-id>`	Gérer les fichiers d'un skill
	`label list/add/remove <skill-id>`	Gérer les étiquettes d'un skill	`add` / `remove` : `<label-id>` accepte un UUID complet ou un préfixe court
`squad`	`list/get/create/update/delete`	Gérer les squads (`delete` archive)
	`member list/add/set-role/remove`	Gérer les membres d'un squad
	`activity <issue-id> <outcome>`	Enregistrer une évaluation du chef
`chat`	`history`, `thread [id]`	Lire la session de messagerie externe qu'un agent traite actuellement	`--limit`, `--before`

Runtime

Commande	Sous-commande	Rôle	Options principales
`daemon`	`start`	Démarrer le daemon local	`--foreground`, `--device-name`, `--runtime-name`, `--workspaces-root`, `--poll-interval`, `--heartbeat-interval`, `--agent-timeout` (`0` signifie aucune limite), `--max-concurrent-tasks`, `--no-auto-update` ; chacune a une variable d'environnement `CLOWLD_*` correspondante
	`stop` / `status` / `restart`	Arrêter, vérifier l'état, redémarrer (`restart` accepte les mêmes options que `start`)
	`logs`	Afficher les journaux du daemon	`--follow`, `--lines`
	`disk-usage`	Afficher l'utilisation du disque local	`--by-workspace`, `--by-task`, `--top`
`runtime`	`list/usage/activity/update/rename/delete`	Consulter et gérer les runtimes	`delete` : `--cascade` (dissocie les agents liés, préserve leurs données et annule leurs exécutions)
	`profile list/create/update/delete`	Gérer les profils de runtime personnalisés
	`profile set-path/unset-path <profile-id>`	Fixer le chemin d'un exécutable local (local uniquement, jamais envoyé au serveur)

Additional

Commande	Sous-commande	Rôle	Options principales
`auth`	`status` / `logout`	Vérifier l'état de l'authentification ; `logout` supprime seulement le jeton enregistré localement et ne le révoque pas côté serveur
`user`	`profile get/update`	Consulter ou mettre à jour le profil de l'utilisateur actuel
`login`	—	Se connecter via le navigateur et configurer automatiquement tous les espaces de travail	`--token` (demande la saisie de façon interactive dans le terminal lorsque l'option est passée sans valeur)
`setup`	`cloud` (par défaut), `self-host`	Enregistrer l'adresse du serveur, finaliser la connexion et démarrer le daemon	`self-host` : `--server-url`, `--app-url`, `--port`, `--frontend-port`
`attachment`	`download <attachment-id>`, `upload <path>`	Télécharger ou envoyer des pièces jointes	`download` : `--output-dir` ; `upload` : `--task`
`config`	`show`, `set <key> <value>`	Consulter ou modifier la configuration locale du profil actuel	Priorité : options de ligne de commande > variables d'environnement > `config.json` > valeurs par défaut intégrées ; définissez une chaîne vide pour effacer une valeur
`update`	—	Mettre à jour le CLI vers la dernière version
`version`	—	Afficher les informations de version	`--output` (`text` ou `json`)

Piloter Clowld Space depuis un autre agent de codage

Si l'essentiel de votre travail se passe déjà dans Codex, Claude Code ou Cursor, vous pouvez piloter Clowld Space depuis ces outils au lieu de basculer vers un terminal. Le skill Clowld Space CLI apprend à ces agents à utiliser les commandes de cette page en toute sécurité : lire les tâches et les fils de commentaires sans gaspiller de tokens, écrire les commentaires via un fichier, et gérer les effets de bord qu'entraînent les mentions, les changements de statut et les assignations.

Il passe entièrement par votre CLI authentifié et n'accorde aucun accès qui lui soit propre : les permissions proviennent toujours de votre connexion, du profil sélectionné et de l'espace de travail. Il nécessite le CLI v0.4.26 ou ultérieur. Le README du dépôt explique l'installation via la marketplace de plugins de Claude Code, l'installateur de skills de Codex, Cursor et tout autre outil qui charge des instructions Markdown.

Étapes suivantes

Skill Clowld Space CLI — piloter Clowld Space depuis Codex, Claude Code ou Cursor.
Authentification et jetons — créer, renouveler et révoquer des PAT.
Dépannage — diagnostiquer les erreurs de commande et les exécutions qui ne démarrent jamais.
Créer et configurer un agent — la sémantique complète de chaque champ de agent create.

Sur cette page