Überblick über CLI-Befehle

Seit den Versionen 14.1.0/13.13.0/12.19.0 stellt die AI Suite Console-Commands bereit, mit denen Integratoren AI-Suite-Operationen, etwa Metadaten-Generierung und Übersetzungen, automatisiert über die Kommandozeile oder den TYPO3-Scheduler ausführen können. Begleitend gibt es das Backend-Modul „AI Suite CLI“ im Bereich Werkzeuge (in TYPO3 v14: Verwaltung) als Status-Übersicht; es ist nur für Administratoren sichtbar. Für den Aufruf der Befehle auf der Konsole ist keine eigene Berechtigung nötig. Die Berechtigung „CLI-/Scheduler-basierte Workflow-Ausführung erlauben“ (enable_cli_workflow_execution) schaltet stattdessen im Backend die Option frei, Workflows aus dem WorkflowManager heraus per CLI im Hintergrund verarbeiten zu lassen; Details unter Berechtigungsmanagement.

Führt einen AI-Suite-Workflow (Metadaten-Generierung oder Übersetzung) aus und legt Aufgaben zur späteren CLI-Verarbeitung an. Wichtigste Optionen:

• --type, -t: Workflow-Typ page, pageTranslate, fileReferences, fileMetadata, fileMetadataTranslation
• --model, -m: zu verwendendes KI-Modell
• --start-from-pid: Start-Seiten-ID (für seitenbasierte Typen)
• --page-type, --depth, --column: Seitentyp-Filter, Traversierungstiefe, zu verarbeitende Spalte. Bei dateibasierten Typen gibt --depth seit den Versionen 14.4.0/13.16.0/12.22.0 die Anzahl der Unterordner-Ebenen unterhalb der angegebenen Verzeichnisse an (0 = nur diese Verzeichnisse, maximal 5)
• --sys-language: Systemsprache im Format <Sprachcode>__<LanguageId>__<Site-Identifier>, z. B. de__0__main
• --source-language, --target-language, --translation-scope (all | metadata | content): für Übersetzungs-Workflows. Quell- und Zielsprache erwarten dasselbe Format wie --sys-language, z. B. --source-language=de__0__main --target-language=en__1__main. Ein ungültiger Sprachwert führt nicht zu einem Fehler: Die AI Suite weicht dann auf eine passende Sprache des Seitenbaums bzw. die Standardsprache aus und schreibt eine Warnung ins Log
• --directory: zu verarbeitende Verzeichnisse, z. B. /, /user_upload/ oder 1:/user_upload/. Seit den Versionen 14.4.0/13.16.0/12.22.0 sind mehrere Verzeichnisse kommasepariert möglich, z. B. /user_upload/,1:/images/
• --show-only-empty, --show-only-used: nur leere Felder bzw. nur verwendete Dateien berücksichtigen
• --prompt: eigener Prompt für die Metadaten-Generierung, ersetzt die vordefinierte Anweisung des gewählten Feldes (seit den Versionen 14.4.0/13.16.0/12.22.0)
• --include-hidden: bezieht versteckte und zeitgesteuerte Seiten mit ein (seit den Versionen 14.5.0/13.17.0/12.23.0). Beachte, dass solche Seiten für eine anonyme Anfrage nicht gerendert werden können, das Abholen ihres Inhalts also in der Regel fehlschlägt

Richtest du den Befehl als Planer-Task ein, bietet das Formular seit den Versionen 14.7.0/13.19.0/12.25.0 Workflow-Typ (--type), Modell (--model) und Spalte (--column) als Auswahllisten statt als freie Textfelder an. Modell und Spalte zeigen nur, was zum gewählten Workflow-Typ passt. Ist der AI-Suite-Server nicht erreichbar, bleibt das Modell ein Textfeld.

Fragt beim Server den Status der Hintergrundaufgaben ab und speichert fertige Ergebnisse. Richte den Befehl am besten als wiederkehrenden Scheduler-Task ein.

Wiederholt fehlgeschlagene CLI-Hintergrundaufgaben, aktuell beschränkt auf den Status task-error.

• --type, -t: Filter nach Aufgabentyp (gleiche Typen wie bei execute-workflow)
• --model, -m: überschreibt das verwendete KI-Modell (ohne Angabe wird das ursprüngliche Modell der Aufgabe genutzt)

Das Modul liegt im Bereich Werkzeuge (in TYPO3 v14: Verwaltung) und ist nur für Administratoren sichtbar. Es zeigt ausstehende und fehlgeschlagene CLI-Aufgaben, gruppiert nach Scope, inklusive Statistik und Typ-Filter. Zusätzlich wird angezeigt, ob der TYPO3-Scheduler verfügbar ist und ob der Befehl ai-suite:process-tasks bereits als Scheduler-Task eingerichtet wurde.

Der typische Ablauf: execute-workflow erzeugt die Aufgaben, process-tasks (idealerweise per Scheduler) verarbeitet sie, das CLI-Modul überwacht den Status und retry-tasks setzt fehlgeschlagene Aufgaben neu auf.

Damit die Hintergrund-Option im WorkflowManager des Backends angeboten wird, müssen alle folgenden Bedingungen erfüllt sein: Die Berechtigung enable_cli_workflow_execution ist gesetzt, EXT:scheduler ist installiert, ein aktiver Scheduler-Task führt ai-suite:process-tasks aus, und der Workflow-Typ wird unterstützt (page, pageTranslate, fileReferences, fileMetadata, fileMetadataTranslation). Auf der Konsole kannst du process-tasks auch ohne Scheduler manuell aufrufen.

Relevante Einstellungen in den Globalen Einstellungen: maxTasks im Bereich „CLI“ (maximale Anzahl an CLI-Hintergrundaufgaben pro Scheduler-Lauf, Standard 50; die Grenze gilt auch für ai-suite:retry-tasks) sowie der DSGVO-Modus im Bereich „Lizenz & Server“. Für die Anzeige der TaskEngine ist außerdem die Berechtigung „Abschnitt ‚TaskEngine‘ im Backend-Modul aktivieren“ (enable_background_task_handling) erforderlich (siehe Berechtigungsmanagement).

Typische Aufrufe, jeweils per Klick kopierbar. [model] durch die Kennung des gewünschten KI-Modells ersetzen.