Skill für offizielle CLI
Du bist eine KI, die einen Glyph-Server über seine CLI steuert. Diese Skill ist eine Karte der gesamten glyph-Befehlsfläche plus der Konventionen, die aus --help nicht ersichtlich sind – insbesondere die Workspace-Scoping-Disziplin, die verhindert, dass deine Befehle mit anderen Clients in Konflikt geraten, und die Exit-Code/Error-Code-Disziplin, die es dir erlaubt, mechanisch auf Fehler zu reagieren.
Einrichtung
glyph injiziert bei der Erstellung einer Aufgabe oder Sitzung die benötigten Umgebungsvariablen:
GLYPH_SERVER– Server-URL (von der CLI automatisch verwendet)GLYPH_WORKSPACE– Workspace-UUID (Workspace-begrenzte Befehle erben sie)
Schnellüberprüfung:
glyph health # Exit-Code 0 ⇒ CLI funktioniert + Server erreichbar
glyph workspace current --json | jq # bestätigt aufgelösten Workspace
Befehlsfläche auf einen Blick
Jeder Workspace-begrenzte Befehl erbt --server / --workspace-id / --output / --json und folgt der untenstehenden gemeinsamen Exit-Code-Tabelle. Die Befehlsgruppen:
| Gruppe | Zweck | Referenz |
|---|---|---|
workspace | Workspaces erstellen / auflisten / anzeigen / aktualisieren / entfernen / neu laden; aktuelle ID ausgeben | references/commands.md#workspace |
session | Interaktive Sitzungen verwalten (auflisten / neu / anzeigen / löschen / Terminal starten) | references/commands.md#session |
task | Einmalige Aufgaben ausführen, auflisten (auch gefiltert nach --origin), inspizieren, Aktivität verfolgen, abbrechen, entfernen | references/commands.md#task |
schedule | Cron-gesteuerte Aufgabenplaner (erstellen / auflisten / patchen / aktivieren / deaktivieren / ausführen / Vorschau / Aufgaben auflisten) | references/commands.md#schedule |
catalog | Agents, Skills, MCPs installieren / synchronisieren / aktivieren / deaktivieren | references/commands.md#catalog |
workflow | Workflow starten, dessen Live-DAG lesen/ändern (expandieren, Knotenspezifikation eines not_started-Knotens via update-spec patchen), auf menschliche Knoten antworten, beenden | references/commands.md#workflow |
runtime | Registrierte Laufzeiten auflisten (Copilot, etc.) | references/commands.md#runtime |
| Server-Inspektion | health, config, status, logs – kein Lebenszyklus | references/commands.md#server-inspection |
| Server-Lebenszyklus | serve / start / stop / restart – nicht Bestandteil dieser Skill | — |
Workspace-Disziplin
Jeder Workspace-begrenzte Befehl benötigt einen expliziten Selektor. Die CLI liest GLYPH_WORKSPACE aus deiner Umgebung (bereits gesetzt), daher funktionieren Befehle direkt:
glyph task dispatch --agent writer --brief "..."
Um auf einem anderen Workspace zu arbeiten, übergib --workspace-id <id> pro Befehl:
glyph task list --workspace-id ws-Y
Die CLI konsultiert keinen serverseitigen, gemeinsamen "aktuellen Workspace"-Zustand – Selektoren sind prozesslokal und immun gegen Störungen durch andere Clients (andere CLI-Sitzungen, Dashboard-Tabs, KI-Agenten auf demselben Server).
Ausgabe-Disziplin
- Für die maschinelle Verarbeitung immer
--jsonübergeben. Das menschenlesbare / Tabellenformat ist kein stabiler Vertrag – Spaltenreihenfolge und -überschriften ändern sich zwischen Versionen. - Für Streaming-Aktivitäten mit
jq -cweiterleiten, um ein Ereignis pro Zeile zu erhalten. - Jede
--json-Form, die du wahrscheinlich verwenden wirst, ist inreferences/json-shapes.mddokumentiert. Konsultiere sie, bevor du einenjq-Filter schreibst – die meisten Formen haben optionale Felder (vorhanden, wenn die zugrunde liegende Zeile nicht null ist), die du als Ankerpunkte verwenden solltest.
Fehler-Disziplin
Fehler auf stderr enthalten immer einen 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
Die Zeile fix: ist dein nächster Befehl, unverändert. Der vollständige code-Katalog (alle Fehlernamen + typischer HTTP-Status + Abhilfe) befindet sich in references/error-codes.md. Insbesondere:
EntryNotReadyErrorist der mit Abstand häufigste Verzweigungspunkt – er enthält einen strukturiertenreason, der beschreibt, ob der Agentack-prereqsbenötigt,disabledist,missingDepsoderblockedDeps(rekursiv) hat. Die Tabelle der Gründe befindet sich inreferences/error-codes.md#entrynotreadyerror-reasons.
Exit-Codes
| Code | Bedeutung | Vorgehen |
|---|---|---|
| 0 | Erfolg | fortsetzen |
| 1 | Generischer Fehler (inkl. fehlender Workspace) | stderr lesen; meist fehlendes Flag/Env |
| 2 | Nutzungsfehler (fehlendes Pflicht-Flag, entfernte Untergruppe) | Aufruf korrigieren; nicht unverändert wiederholen |
| 3 | Server nicht erreichbar | Benutzer bitten, glyph start auszuführen oder --server zu prüfen |
| 4 | Server hat 4xx/5xx zurückgegeben | code in stderr lesen; references/error-codes.md konsultieren |
Exit-Code 2 bedeutet "der Befehl selbst ist falsch" – wiederhole ihn niemals, ohne den Aufruf zu ändern. Exit-Code 4 bedeutet "der Server hat dies abgelehnt" – lies das code-Feld, es sagt dir den nächsten Schritt.
Fallstricke
- Um auf eine Aufgabe zu warten, verwende
glyph task activity <tid> --follow(Echtzeit-SSE). Das Abfragen vontask listin einer Shell-Schleife verschwendet Zyklen und hinkt den echten Ereignissen hinterher. - Für eine einmalige "Was ist bisher passiert?"-Momentaufnahme entferne
--follow–glyph task activity <tid> --jsongibt die aktuelle Aktivität plustotalItemsin einem Aufruf zurück.--followblockiert, bis die Aufgabe beendet ist. - Beende vor dem Entfernen. Ein einfaches
task rm <tid>setzt voraus, dass die Aufgabe in einem Endzustand ist (succeeded/failed/cancelled); wenn sie noch läuft, rufe zuerstglyph task cancel <tid>auf, danntask rm. Greife nur zu--purge, wenn du auch das Arbeitsverzeichnis und den Laufzeitzustand entfernen möchtest (dann iststderr.logfür die Nachlese verloren). Gleiche Unterscheidung beisession rmundworkspace rm. - Setze
--followimmer mit der ausgegebenenlast seq:fort. Bei jedem sauberen Exit (event: endoder Stream geschlossen) UND bei einem Fehler mitten im Stream gibt die CLIlast seq: <N>auf stderr aus – übergib--after <N>beim nächsten--follow-Aufruf, um ohne Lücken oder Duplikate fortzusetzen. Strg+C ist die Ausnahme (stderr wird nicht geleert); leite die Seq aus dem letzten stdout-NDJSON-Element ab (... | tail -1 | jq .seq). Das vollständige Wiederaufnahme-Playbook befindet sich inreferences/playbooks.md#monitor-a-long-running-task. - Workspace-IDs immer von
glyph workspace list --json | jqbeziehen. Dashboard-URL-Fragmente driften zwischen Versionen und sind kein stabiler Vertrag. schedule patchist dünn besiedelt – nur die übergebenen Flags werden auf die Leitung gelegt. Um ein Feld zu entfernen, übergib--clear-details/--clear-runtime(ein leeres--details ""wird als weggelassen behandelt, nicht als Löschung).
Referenzen (obligatorische Lektüre vor nicht-trivialen Arbeiten)
references/commands.md– Referenz der Unterbefehle pro Gruppe (workspace / session / task / schedule / catalog / workflow / runtime / server inspection). Einmal überfliegen, als Nachschlagewerk behalten.references/playbooks.md– Mehrschrittige, zielorientierte Playbooks (Agent installieren und verifizieren, Aufgabe ausführen und warten, Aufgabe überwachen, Eintrag synchronisieren, aufräumen, neuen Workspace einrichten, lokalen Agenten spontan erstellen).references/json-shapes.md– Die gängigen--json-Payload-Formen mit konkreten Feldlisten und Hinweisen zur Optionalität.references/error-codes.md– Jedercode-Wert, den der Server ausgibt, plus der passendeglyph-Befehl zur Behebung.