Compétence official/cli
Vous êtes une IA contrôlant un serveur glyph via son CLI. Cette compétence est une carte de toute la surface de commande glyph ainsi que des conventions qui ne sont pas évidentes dans --help — principalement la discipline de portée de workspace qui empêche vos commandes d'entrer en conflit avec d'autres clients, et la discipline des codes de sortie / codes d'erreur qui vous permet de réagir mécaniquement aux échecs.
Configuration
glyph injecte ce dont vous avez besoin dans votre environnement lorsqu'il lance votre tâche ou session :
GLYPH_SERVER— URL du serveur (le CLI l'utilise automatiquement)GLYPH_WORKSPACE— UUID du workspace (les commandes limitées au workspace l'héritent)
Vérification rapide :
glyph health # exit 0 ⇒ CLI fonctionne + serveur accessible
glyph workspace current --json | jq # confirme le workspace résolu
Aperçu de la surface de commande
Chaque commande limitée à un workspace hérite de --server / --workspace-id / --output / --json et suit le tableau des codes de sortie partagé ci-dessous. Les groupes de sous-commandes :
| Groupe | Objectif | Référence |
|---|---|---|
workspace | Créer / lister / afficher / mettre à jour / supprimer / recharger des workspaces ; afficher l'identifiant courant | references/commands.md#workspace |
session | Gérer les sessions interactives (lister / nouvelle / afficher / supprimer / lancer un terminal) | references/commands.md#session |
task | Lancer des tâches ponctuelles, lister (y compris filtré par --origin), inspecter, suivre l'activité, annuler, supprimer | references/commands.md#task |
schedule | Lanceurs de tâches déclenchés par cron (créer / lister / modifier / activer / désactiver / exécuter / prévisualiser / lister les tâches) | references/commands.md#schedule |
catalog | Installer / synchroniser / activer / désactiver des agents, compétences, MCP | references/commands.md#catalog |
workflow | Amorcer un workflow, lire/modifier son DAG en direct (développer, modifier la spécification d'un nœud not_started via update-spec), répondre aux nœuds humains, terminer | references/commands.md#workflow |
runtime | Lister les runtimes enregistrés (copilot, etc.) | references/commands.md#runtime |
| Inspection du serveur | health, config, status, logs — pas de cycle de vie | references/commands.md#server-inspection |
| Cycle de vie du serveur | serve / start / stop / restart — hors de portée pour cette compétence | — |
Discipline du workspace
Chaque commande limitée à un workspace nécessite un sélecteur explicite. Le CLI lit GLYPH_WORKSPACE depuis votre environnement (déjà défini), donc les commandes fonctionnent telles quelles :
glyph task dispatch --agent writer --brief "..."
Pour agir sur un autre workspace, passez --workspace-id <id> par commande :
glyph task list --workspace-id ws-Y
Le CLI ne consulte aucun état partagé de type "workspace courant" côté serveur — les sélecteurs sont locaux au processus, à l'abri des interférences d'autres clients (autres sessions CLI, onglets du tableau de bord, agents IA sur le même serveur).
Discipline de sortie
- Pour l'analyse, passez toujours
--json. Le format humain/tableau n'est pas un contrat stable — l'ordre des colonnes et les en-têtes changent entre les versions. - Pour le streaming d'activité, utilisez
jq -cpour conserver un événement par ligne. - Chaque forme
--jsonque vous êtes susceptible de consommer est documentée dansreferences/json-shapes.md. Consultez-le avant d'écrire un filtrejq— la plupart des formes ont des champs optionnels (présents lorsque la ligne sous-jacente est non nulle) sur lesquels vous devez vous baser.
Discipline des erreurs
Les erreurs sur stderr portent toujours un code :
agent "writer" is not ready: prereqs not acknowledged (HTTP 409, EntryNotReadyError)
agent: acme/writer
cause: prereqs not acknowledged
fix: glyph catalog agent ack-prereqs acme/writer
La ligne fix: est votre prochaine commande, textuellement. Le catalogue complet des code (tous les noms d'erreur + HTTP typique + correction) se trouve dans references/error-codes.md. En particulier :
EntryNotReadyErrorest la ramification la plus courante que vous rencontrerez — il porte unereasonstructurée décrivant si l'agent nécessiteack-prereqs, estdisabled, amissingDeps, ou ablockedDeps(qui récursent). Le tableau des raisons se trouve dansreferences/error-codes.md#entrynotreadyerror-reasons.
Codes de sortie
| code | signification | conduite à tenir |
|---|---|---|
| 0 | succès | continuer |
| 1 | erreur générique (incl. workspace manquant) | lire stderr ; généralement un indicateur/env manquant |
| 2 | erreur d'utilisation (indicateur requis manquant, sous-commande supprimée) | corriger l'invocation ; ne pas réessayer telle quelle |
| 3 | serveur inaccessible | demander à l'utilisateur de glyph start ou vérifier --server |
| 4 | le serveur a renvoyé 4xx/5xx | lire code dans stderr ; consulter references/error-codes.md |
Le code de sortie 2 signifie "la commande elle-même est erronée" — ne la réessayez jamais sans modifier l'invocation. Le code de sortie 4 signifie "le serveur a rejeté ceci" — lisez le champ code, il vous indique la prochaine action.
Pièges
- Pour attendre une tâche, utilisez
glyph task activity <tid> --follow(SSE en temps réel). Interrogertask listdans une boucle shell gaspille des cycles et retarde les événements réels. - Pour un instantané ponctuel "que s'est-il passé jusqu'à présent ?", omettez
--follow—glyph task activity <tid> --jsonrenvoie l'activité courante plustotalItemsen un seul appel.--followbloque jusqu'à la fin de la tâche. - Terminez avant de supprimer. Une simple
task rm <tid>nécessite que la tâche soit dans un état terminal (succeeded/failed/cancelled) ; si elle est encore en cours d'exécution, faites d'abordglyph task cancel <tid>, puistask rm. N'utilisez--purgeque lorsque vous voulez également supprimer le répertoire de travail + l'état d'exécution (lestderr.logpost-mortem est perdu). Même distinction poursession rmetworkspace rm. - Reprenez toujours
--followavec lelast seq:affiché. À chaque sortie propre (event: endou flux fermé) ET à chaque sortie sur erreur en milieu de flux, le CLI imprimelast seq: <N>sur stderr — passez--after <N>lors de la prochaine invocation de--followpour reprendre sans trous ni doublons. Ctrl+C est l'exception (stderr n'est pas vidé) ; dérivez le seq du dernier élément NDJSON de stdout à la place (... | tail -1 | jq .seq). Le manuel complet de reprise se trouve dansreferences/playbooks.md#monitor-a-long-running-task. - Obtenez toujours les identifiants de workspace depuis
glyph workspace list --json | jq. Les fragments d'URL du tableau de bord varient entre les versions et ne sont pas un contrat filaire. schedule patchest parcimonieux — seuls les indicateurs que vous passez sont envoyés sur le fil. Pour supprimer un champ, passez--clear-details/--clear-runtime(un--details ""vide est traité comme omis, pas comme une suppression).
Références (lecture obligatoire avant tout travail non trivial)
references/commands.md— référence des sous-commandes par groupe (workspace / session / task / schedule / catalog / workflow / runtime / inspection du serveur). Parcourez une fois, conservez comme référence.references/playbooks.md— manuels multi-étapes orientés objectifs (installer et vérifier un agent, lancer et attendre, surveiller une tâche, synchroniser une entrée, nettoyer, intégrer un nouveau workspace, créer un agent local à la volée).references/json-shapes.md— les formes courantes des charges utiles--jsonavec des listes de champs concrètes et des notes d'optionalité.references/error-codes.md— chaque valeur decodeque le serveur émet + la commandeglyphcorrespondante pour la corriger.