Task-Kommandos

clye task erstellt, lädt und steuert Tasks in AI Hub über die REST-API. Die Commands verwenden dieselbe Authentifizierung wie MCP (--url / AI_HUB_URL und --api-key / AI_HUB_API_KEY). Aus einer Hub-URL wie https://clye.ai oder https://clye.ai/api/mcp leitet die CLI automatisch die REST-Basis …/api ab.

Ein zentrales Konzept ist der Task-Kontext: Setze AI_HUB_TASK_ID oder übergib --task-id, dann verwenden zielbezogene Unterbefehle diese ID automatisch. task create erstellt in diesem Kontext standardmäßig einen Subtask, außer du setzt --subtask-of, gibst subtaskOf in --json-file an oder nutzt --no-parent.

Globale Task-Flags

Flag	Beschreibung
--task-id	Default-Task-UUID für Befehle mit optionalem Task-Argument; Standard aus AI_HUB_TASK_ID.
--full-json	Gibt die vollständige API-Antwort aus, inklusive null- und false-Feldern.

Task erstellen

clye task create \
  --name "Daten prüfen" \
  --description "CSV importieren und validieren" \
  --space-id 00000000-0000-0000-0000-000000000000 \
  --agent-id 11111111-1111-1111-1111-111111111111 \
  --priority high \
  --data '{"source":"upload.csv"}'

clye task create --json-file task.json
cat task.json | clye task create --json-file -

Flag	Beschreibung
--data	JSON-Objekt für data; der Task-Typ ist immer agent.
--json-file	Vollständiger JSON-Body als Datei oder - für stdin. Nicht mit anderen Create-Flags kombinieren.
--name	Anzeigename.
--title	Alias für --name; darf nicht von --name abweichen.
--description	Beschreibung.
--space-id	Space-UUID.
--agent-id	Agent-UUID. Wenn du die UUID eines erwähnten Assistenten-Spaces schon hast, kannst du diese direkt verwenden (zum Beispiel aus einem /spaces/{uuid}-Link).
--tool-id	Tool-ID.
--priority	Priorität als Label: low, medium, high, critical oder extreme. Legacy-Zahlen werden weiterhin akzeptiert, empfohlen sind aber die Labels.
--max-retries	Maximale Wiederholungen; Standard 3.
--scheduled-for	Geplanter Startzeitpunkt als ISO-8601-Zeit.
--deadline	Deadline als ISO-8601-Zeit. Wenn du nur ein Datum ohne Uhrzeit übergibst, gilt es als Frist bis zum Tagesende dieses Datums.
--subtask-of	Parent-Task-UUID(s); wiederholbar oder kommagetrennt. Überschreibt automatischen Parent.
--no-parent	Erstellt einen Top-Level-Task trotz --task-id oder AI_HUB_TASK_ID.
--blocks	Task-UUID(s), die durch diesen Task blockiert werden.
--blocked-by	Task-UUID(s), die vorher abgeschlossen sein müssen.
--subscribers	Abonnenten für die neue Aufgabe. Erlaubt User- oder Space-UUIDs; mehrfach, kommagetrennt oder über den JSON-Body.

Abonnenten direkt beim Erstellen mitgeben

Wenn eine neue Aufgabe von Anfang an von bestimmten Personen oder Spaces beobachtet werden soll, kannst du diese beim Erstellen direkt als Abonnenten mitgeben.

Beispiel:

clye task create \
  --name "Angebot prüfen" \
  --space-id 00000000-0000-0000-0000-000000000000 \
  --subscribers 22222222-2222-2222-2222-222222222222,33333333-3333-3333-3333-333333333333

Das ist praktisch, wenn Benachrichtigungen und Folgeaktivität direkt ab dem Anlegen der Aufgabe für die richtigen Beteiligten laufen sollen.

Mehrere zusammenhängende Tasks sauber anlegen

Wenn mehrere neue Tasks zusammengehören, ist eine feste Verknüpfung über --blocked-by, --blocks oder --subtask-of in der Regel sinnvoller als später aktiv auf Statusänderungen zu warten.

Faustregel:

• --blocked-by: Dieser Task darf erst starten, wenn andere Tasks abgeschlossen sind.
• --blocks: Andere Tasks hängen von diesem Task ab.
• --subtask-of: Dieser Task ist Teil einer übergeordneten Aufgabe.

Das hält die Reihenfolge direkt im Task-Modell sichtbar und ist für längere Abläufe robuster als manuelles Polling.

Task laden und Status steuern

clye task get <task-id>
clye task --task-id <task-id> start
clye task --task-id <task-id> pause
clye task --task-id <task-id> stop

Unterbefehl	Argumente	Beschreibung
get	[<task-id>]	Lädt einen Task. Ohne Argument wird --task-id bzw. AI_HUB_TASK_ID verwendet.
start	[<task-id>]	Markiert den Task als laufend.
pause	[<task-id>]	Pausiert einen laufenden Task.
stop	[<task-id>]	Ruft dieselbe API wie pause auf.

Abschließen, Fehler und Fortschritt

clye task complete <task-id> \
  --message "Fertig" \
  --result '{"rows":1200,"valid":1198}'

clye task fail <task-id> --message "Importdatei fehlt"
clye task progress <task-id> --percent 65 --message "Validierung läuft"

Unterbefehl	Flags	Beschreibung
complete	--result, --message	Schließt den Task erfolgreich ab. --result muss gültiges JSON sein.
fail	--message	Markiert den Task als fehlgeschlagen; --message ist Pflicht.
progress	--percent, --message	Meldet Fortschritt von 0 bis 100; --percent ist Pflicht.

Aktualisieren und Queues lesen

clye task update <task-id> --json-file update.json
clye task next --type agent --timeout-ms 30000
clye task list --limit 100
clye task list --parent-id <task-id>
clye task list --all
clye task upcoming --type agent

Unterbefehl	Flags	Beschreibung
update	--json-file	Ändert Felder eines Tasks per JSON-Body; Datei oder - für stdin.
next	--type, --timeout-ms	Wartet auf den nächsten Task und claimed ihn für den Worker. --type ist wiederholbar, --timeout-ms erlaubt 0 bis 120000.
list	--limit, --parent-id, --all	Listet Tasks. Standardmäßig werden bei gesetztem Kontext Subtasks dieses Tasks gefiltert.
upcoming	--type	Listet geplante Tasks, deren Zeitpunkt noch nicht erreicht ist.

Kurz auf einen Task warten

Für kurze technische Abläufe kannst du den Status eines Tasks auch aktiv abfragen und kurz warten, bis er einen Zielstatus erreicht. Das ist vor allem direkt nach dem Anlegen oder Starten eines Tasks sinnvoll.

Wichtige Punkte:

• Standardmäßig endet das Warten bei completed, cancelled, failed oder waiting.
• Mit mode=all müssen alle beobachteten Tasks einen Zielstatus erreichen.
• Mit mode=any reicht der erste passende Task.
• Standard-Timeout: 120 Sekunden
• Maximales Timeout: 600 Sekunden

Für längere fachliche Abhängigkeiten solltest du weiterhin echte Task-Beziehungen wie --blocked-by oder --subtask-of verwenden.