Overview of CLI commands

Since versions 14.1.0/13.13.0/12.19.0, the AI Suite provides console commands that allow integrators to automate AI Suite operations, such as metadata generation and translations, via the command line or the TYPO3 scheduler. In addition, the backend module “AI Suite CLI” in the Tools area (in TYPO3 v14: Administration) serves as a status overview. It is only visible to administrators. Calling the commands on the console requires no separate permission. Instead, the permission “Allow CLI/Scheduler-based workflow execution” (enable_cli_workflow_execution) unlocks the option in the backend to have workflows from the WorkflowManager processed in the background via CLI. Details under Permission management.

Executes an AI Suite workflow (metadata generation or translation) and creates tasks for later CLI processing. Main options:

• --type, -t: Workflow type page, pageTranslate, fileReferences, fileMetadata, fileMetadataTranslation
• --model, -m: AI model to use
• --start-from-pid: Start page ID (for page-based types)
• --page-type, --depth, --column: Page type filter, traversal depth, column to process. Since versions 14.4.0/13.16.0/12.22.0, --depth sets the number of subfolder levels below the given directories for file-based types (0 = only these directories, maximum 5)
• --sys-language: System language in the format <language code>__<LanguageId>__<site identifier>, e.g. de__0__main
• --source-language, --target-language, --translation-scope (all | metadata | content): for translation workflows. Source and target language expect the same format as --sys-language, e.g. --source-language=de__0__main --target-language=en__1__main. An invalid language value does not cause an error: the AI Suite then falls back to a matching language of the page tree or the default language and writes a warning to the log
• --directory: Directories to process, e.g. /, /user_upload/ or 1:/user_upload/. Since versions 14.4.0/13.16.0/12.22.0, several directories are possible, separated by commas, e.g. /user_upload/,1:/images/
• --show-only-empty, --show-only-used: consider only empty fields or only used files
• --prompt: own prompt for metadata generation, replaces the predefined instruction of the selected field (since versions 14.4.0/13.16.0/12.22.0)
• --include-hidden: includes hidden and time-restricted pages (since versions 14.5.0/13.17.0/12.23.0). Note that such pages cannot be rendered for an anonymous request, so fetching their content usually fails

Since versions 14.7.0/13.19.0/12.25.0, the form of a scheduler task for this command offers workflow type (--type), model (--model) and column (--column) as dropdowns instead of free text fields. Model and column only list what fits the selected workflow type. If the AI Suite server cannot be reached, the model stays a text field.

Queries the server for the status of the background tasks and stores completed results. Ideally, set up the command as a recurring scheduler task.

Retries failed CLI background tasks, currently limited to the status task-error.

• --type, -t: Filter by task type (same types as in execute-workflow)
• --model, -m: overrides the AI model used (if not specified, the original model of the task is used)

The module is located in the Tools area (in TYPO3 v14: Administration) and is only visible to administrators. It displays pending and failed CLI tasks, grouped by scope, including statistics and type filters. Additionally, it shows whether the TYPO3 scheduler is available and whether the command ai-suite:process-tasks has already been set up as a scheduler task.

The typical process: execute-workflow generates the tasks, process-tasks (ideally via scheduler) processes them, the CLI module monitors the status, and retry-tasks resets failed tasks.

For the background option to be offered in the WorkflowManager of the backend, all of the following conditions must be met: the permission enable_cli_workflow_execution is set, EXT:scheduler is installed, an active scheduler task runs ai-suite:process-tasks, and the workflow type is supported (page, pageTranslate, fileReferences, fileMetadata, fileMetadataTranslation). On the console, you can also call process-tasks manually without the scheduler.

Relevant settings in the Global Settings: maxTasks in the “CLI” area (maximum number of CLI background tasks per scheduler run, default 50; the limit also applies to ai-suite:retry-tasks) as well as the GDPR mode in the “License & server” area. To display the TaskEngine, the permission “Enable TaskEngine section within backend module” (enable_background_task_handling) is also required (see Permission management).

Typical calls, each can be copied by clicking. Replace [model] with the identifier of the desired AI model.