MtoRagSystem/COMMAND_REF.md

RetrieX – CLI Command Reference

Basis: rag.zip (aktueller Code-Stand vom 2026-04-15)
Scope: ausschließlich projektspezifische Symfony-Commands unter src/Command
Namespace-Konvention: mto:agent:*

Diese Referenz ist gegen den realen Codebestand abgeglichen und ersetzt die veraltete Fassung der bisherigen COMMAND_REF.md.

---

1. Überblick

Command	Bereich	Kurzbeschreibung
mto:agent:chat	Agent / CLI	Interaktiver Terminal-Chat gegen den AgentRunner
mto:agent:ingest:version	Ingest	Startet einen Ingest für eine konkrete Dokumentversion
mto:agent:ingest:run	Ingest Jobs	Führt einen vorhandenen IngestJob aus
mto:agent:system:rebuild	System	Globaler Hard-Rebuild von Chunks, Vektorindex, Tags und optional Service-Reload
mto:agent:config:validate	Config / Governance	Validiert die effektive RetrieX-Konfiguration
mto:agent:config:audit-source	Config / Governance	Auditiert YAML-Mappings gegen PHP-Fallbacks und Defaults
mto:agent:config:dump-effective	Config / Governance	Gibt die effektive Konfigurationsinventur aus
mto:agent:regression:test	Config / Governance	Fuehrt Offline-Regression-Guards fuer stabile Pfade aus
mto:agent:vector:rebuild	Vector	Baut den Chunk-Vektorindex aus index.ndjson neu
mto:agent:vector:control	Vector Service	Install, Start, Stop, Reload und Status des Python-Vector-Service
mto:agent:vector:health	Vector	Konsistenzcheck für Chunk-NDJSON und Vektorindex
mto:agent:test-vector	Debug	Führt Tag-Routing und Chunk-Retrieval für einen Testprompt aus
mto:agent:tags:export	Tags	Exportiert Tags nach tags.ndjson
mto:agent:tags:rebuild	Tags	Exportiert Tags und baut vector_tags.index neu
mto:agent:tags:job:run	Tag Jobs	Führt einen vorhandenen Tag-Rebuild-Job aus oder erstellt direkt einen neuen
mto:agent:tag:health	Tags	Konsistenzcheck für tags.ndjson und Tag-Vektorindex
mto:agent:test:shop-search	Commerce / Debug	Testkommando für die Shopware-Suche
mto:agent:user:create	User	Interaktive Anlage eines Users

---

2. Agent / Chat

mto:agent:chat

Interaktiver CLI-Chat mit dem Agenten.

Signatur

bin/console mto:agent:chat [user-id]

Argumente

• user-id optional, Default: cli

Reales Verhalten im Code

• startet eine Terminal-Schleife mit Question → Answer
• ruft pro Eingabe AgentRunner->run($prompt, $userId) auf
• streamt Tokens direkt ins Terminal
• beendet sich bei EOF, leerer Eingabe oder exit

Beispiel

bin/console mto:agent:chat
bin/console mto:agent:chat admin-debug

---

3. Ingest / Jobs

mto:agent:ingest:version

Startet einen Ingest für eine konkrete DocumentVersion mit explizitem Benutzerkontext.

Signatur

bin/console mto:agent:ingest:version <versionId> <userId>

Argumente

• versionId erforderlich, UUID einer DocumentVersion
• userId erforderlich, UUID des auslösenden Users

Reales Verhalten im Code

• lädt DocumentVersion und User aus Doctrine
• bricht mit Fehler ab, wenn Version oder User nicht existieren
• ruft IngestOrchestrator->runForVersion($version, $user) auf
• gibt nach Abschluss die erzeugte Job-ID aus

Beispiel

bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>

Wichtige Korrektur zur alten Doku Die bisherige Referenz dokumentierte nur einen Parameter. Im aktuellen Code sind zwei Pflichtargumente erforderlich.

---

mto:agent:ingest:run

Führt einen bereits existierenden IngestJob aus.

Signatur

bin/console mto:agent:ingest:run <jobId> [--dry-run]

Argumente / Optionen

• jobId erforderlich, UUID eines IngestJob
• --dry-run optional, simuliert schwere Operationen ohne tatsächliche Ausführung

Reales Verhalten im Code

• lädt den Job aus der Datenbank
• bricht mit Fehler ab, wenn der Job nicht gefunden wird
• beendet sich erfolgreich, wenn der Job bereits terminal ist (COMPLETED, FAILED, ABORTED)
• ruft sonst IngestOrchestrator->runExistingJob($job, $dryRun) auf

Beispiele

bin/console mto:agent:ingest:run <jobUuid>
bin/console mto:agent:ingest:run <jobUuid> --dry-run

---

mto:agent:system:rebuild

Globaler Hard-Rebuild des Systems.

Signatur

bin/console mto:agent:system:rebuild --hard [--no-tags] [--no-reload] [--no-health] [--dry-run]

Optionen

• --hard Pflicht-Sicherheitsschalter; ohne diese Option bricht das Kommando ab
• --no-tags überspringt den Tag-Rebuild
• --no-reload überspringt Reload/Start des Vector-Service
• --no-health überspringt den abschließenden Health-Check
• --dry-run simuliert den Reindex ohne Schreiboperationen

Reales Verhalten im Code

1. erzeugt einen neuen IngestJob vom Typ GLOBAL_REINDEX
2. führt den globalen Reindex über den Orchestrator aus
3. exportiert optional tags.ndjson und baut vector_tags.index neu
4. startet bzw. reloadet optional den Python-Vector-Service
5. führt optional Chunk- und Tag-Health-Checks aus

Beispiele

bin/console mto:agent:system:rebuild --hard
bin/console mto:agent:system:rebuild --hard --dry-run
bin/console mto:agent:system:rebuild --hard --no-tags --no-reload

Hinweis Dieses Kommando ist aktuell der zentrale Produktions-Entry-Point für einen vollständigen Neuaufbau des Retrieval-Stacks.

---

4. Vector / Retrieval

mto:agent:vector:rebuild

Baut den Chunk-Vektorindex neu.

Signatur

bin/console mto:agent:vector:rebuild

Reales Verhalten im Code

• schreibt Rebuilding vector index...
• ruft VectorIndexBuilder->rebuildFromNdjson() auf
• schreibt anschließend Done.

Beispiel

bin/console mto:agent:vector:rebuild

---

mto:agent:vector:control

Steuert den persistenten Python-Vector-Service über python/vector/vector_control.py.

Signatur

bin/console mto:agent:vector:control [optionen]

Unterstützte Optionen

• --install installiert fehlende Python-Dependencies in .venv
• --start startet den Service, falls er nicht läuft
• --stop stoppt den Service anhand der PID-Datei
• --force erzwingt einen Hard-Stop
• --reload triggert den /reload-Endpoint des Service
• --status gibt den aktuellen Status aus
• --foreground startet im Vordergrund
• --port=8090 setzt den Port
• --host=0.0.0.0 setzt den Host

Reales Verhalten im Code

• baut einen Prozessaufruf gegen .venv/bin/python python/vector/vector_control.py
• reicht gesetzte Optionen durch
• hängt immer --port und --host an
• gibt stdout des Python-Skripts direkt aus

Beispiele

bin/console mto:agent:vector:control --install
bin/console mto:agent:vector:control --start
bin/console mto:agent:vector:control --status
bin/console mto:agent:vector:control --reload
bin/console mto:agent:vector:control --stop --force

---

mto:agent:vector:health

Health-Check für Chunk-NDJSON und Chunk-Vektorindex.

Signatur

bin/console mto:agent:vector:health

Reales Verhalten im Code

• ruft VectorIndexHealthService->check() auf
• gibt den Report als JSON aus
• endet mit Exit-Code 0, wenn status mit OK beginnt; sonst 1

Beispiel

bin/console mto:agent:vector:health

---

mto:agent:test-vector

Debug-Kommando für einen realistischen Retrieval-Test.

Signatur

bin/console mto:agent:test-vector <prompt>

Argumente

• prompt erforderlich, Testanfrage für das Retrieval

Reales Verhalten im Code

• führt zuerst Tag-Routing über TagVectorSearchClient aus
• führt danach Chunk-Retrieval über VectorSearchClient aus
• misst Tag-, Chunk- und Gesamtdauer
• gibt beide Result-Sets als JSON aus

Beispiel

bin/console mto:agent:test-vector "welche dokumente behandeln den ingest-flow?"

---

5. Tag-System

mto:agent:tags:export

Exportiert die Tag-Datenbasis nach tags.ndjson.

Signatur

bin/console mto:agent:tags:export

Reales Verhalten im Code

• ruft TagNdjsonExporter->export() auf
• gibt Pfad, Tag-Anzahl, Zeilen und Bytes aus

Beispiel

bin/console mto:agent:tags:export

---

mto:agent:tags:rebuild

Kompletter Neuaufbau des Tag-Retrievals.

Signatur

bin/console mto:agent:tags:rebuild

Reales Verhalten im Code

1. exportiert tags.ndjson
2. baut vector_tags.index
3. setzt einen Runtime-Marker über IndexMetaManager->touchRuntime()

Beispiel

bin/console mto:agent:tags:rebuild

---

mto:agent:tags:job:run

Führt einen Tag-Rebuild-Job mit File-Lock aus.

Signatur

bin/console mto:agent:tags:job:run [jobId] [--create]

Argumente / Optionen

• jobId optional, UUID eines bestehenden TagRebuildJob
• --create optional, erstellt und startet sofort einen neuen TagRebuildJob

Regeln im Code

• entweder jobId oder --create
• beides zusammen ist ungültig
• keines von beiden ist ebenfalls ungültig

Reales Verhalten im Code

• markiert den Job auf RUNNING
• sperrt parallel laufende Tag-Rebuilds per File-Lock
• exportiert tags.ndjson
• baut vector_tags.index
• markiert den Job bei Erfolg als COMPLETED, sonst als FAILED

Beispiele

bin/console mto:agent:tags:job:run --create
bin/console mto:agent:tags:job:run <jobUuid>

---

mto:agent:tag:health

Health-Check für das Tag-Retrieval.

Signatur

bin/console mto:agent:tag:health

Reales Verhalten im Code

• ruft TagVectorIndexHealthService->check() auf
• gibt den Report als JSON aus
• endet mit Exit-Code 0, wenn status mit OK beginnt; sonst 1

Beispiel

bin/console mto:agent:tag:health

Wichtige Korrektur zur alten Doku Der reale Command-Name ist tag:health (Singular), nicht tags:health.

---

6. Commerce / Shopware Debug

mto:agent:test:shop-search

Testkommando für die Shopware-Suche.

Signatur

bin/console mto:agent:test:shop-search [query]

Argumente

• query optional
• Default im Code: zeige mir testomat modelle wasserhärte unter 5000 euro

Beabsichtigtes Verhalten

• ruft die Shop-Suche auf
• gibt pro Treffer Produktdaten wie ID, Produktnummer, Hersteller, Preis, Verfügbarkeit, URL und Description aus

Wichtiger Code-Hinweis Im aktuellen Stand von rag.zip ruft das Command ShopSearchService->search($query) mit einem Argument auf, die Service-Signatur erwartet aber zwei Argumente (string $originalPrompt, string $commerceIntent). Das Kommando ist daher im aktuellen Codebestand sehr wahrscheinlich nicht lauffähig, solange diese Signaturabweichung nicht behoben wird.

---

7. User-Management

mto:agent:user:create

Interaktive Anlage eines Users.

Signatur

bin/console mto:agent:user:create

Interaktiver Ablauf

1. E-Mail eingeben
2. Passwort eingeben
3. Rolle wählen

Validierungen im Code

• E-Mail muss valide sein
• User mit gleicher E-Mail darf nicht bereits existieren
• Passwort muss mindestens 8 Zeichen lang sein

Im Code auswählbare Rollen

• ROLE_SUPER_ADMIN
• ROLE_KNOWLEDGE_ADMIN
• ROLE_EDITOR
• ROLE_USER

Beispiel

bin/console mto:agent:user:create

---

8. Typische Betriebsabläufe

Manueller Ingest einer Version

bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>

Vorhandenen Ingest-Job ausführen

bin/console mto:agent:ingest:run <jobUuid>

Nur Chunk-Vektorindex neu bauen

bin/console mto:agent:vector:rebuild

Gesamtsystem hart neu aufbauen

bin/console mto:agent:system:rebuild --hard

Vector-Service prüfen und reloaden

bin/console mto:agent:vector:health
bin/console mto:agent:vector:control --reload

Tag-Retrieval neu aufbauen

bin/console mto:agent:tags:rebuild
bin/console mto:agent:tag:health

---

9. Wichtige Runtime-Dateien und Pfade

Die bisherige Doku nannte teilweise veraltete Pfade unter var/. Im aktuellen Code liegen die Knowledge-Artefakte primär unter var/knowledge/.

var/
├── knowledge/
│   ├── index.ndjson
│   ├── index_meta.json
│   ├── index_runtime.json
│   ├── vector.index
│   ├── vector.index.meta.json
│   ├── tags.ndjson
│   ├── vector_tags.index
│   ├── vector_tags.index.meta.json
│   ├── uploads/
│   └── locks/
│       └── tag_rebuild.lock
├── run/
│   └── vector_service.pid
└── locks/
    └── ingest.lock

Herkunft im Code

• config/services.yaml definiert mto.knowledge.root = %mto.root%/var/knowledge
• python/vector/vector_control.py verwendet var/run/vector_service.pid
• App\Service\LockService verwendet aktuell var/locks/ingest.lock

---

10. Wichtige Abweichungen zur alten COMMAND_REF.md

Die bisherige Datei war in mehreren Punkten nicht mehr codekonform. Wesentliche Korrekturen:

1. mto:agent:system:rebuild fehlte vollständig
2. mto:agent:test:shop-search fehlte vollständig
3. mto:agent:tag:health fehlte und war zudem leicht falsch benannt
4. mto:agent:ingest:version braucht aktuell <versionId> <userId>
5. Runtime-Dateien liegen nicht nur unter var/, sondern überwiegend unter var/knowledge/
6. der globale Rebuild läuft heute über mto:agent:system:rebuild --hard, nicht über ein dokumentiertes ingest:global

---

11. Config-Governance / YAML-only Guardrails

These commands are mandatory for changes that touch YAML-backed configuration, prompt/retrieval behavior, intent detection, commerce/shop logic or regression-sensitive answer paths.

mto:agent:config:validate

Validates the effective RetrieX configuration.

Signature

bin/console mto:agent:config:validate [--json]

Expected result before merge

• status OK
• no errors

mto:agent:config:audit-source

Audits YAML-backed configuration against remaining PHP defaults, fallback accessors and constructor defaults.

Signature

bin/console mto:agent:config:audit-source [--details] [--json]

Expected result before merge

• no missing YAML mappings
• no new undocumented PHP-only semantic constants
• no constructor defaults without YAML/service-parameter mapping

Use --details for reviewable console output and --json for machine-readable CI output.

mto:agent:config:dump-effective

Dumps the effective RetrieX configuration inventory.

Signature

bin/console mto:agent:config:dump-effective [--summary]

Use --summary for a compact review view.

mto:agent:regression:test

Runs offline regression guards for stable configuration paths.

Signature

bin/console mto:agent:regression:test [--json]

Expected result before merge

• status OK
• all checks pass

This command protects the regression-sensitive 1.4.2/1.5.0 baseline, especially the Testomat 808 / 0,02 deg dH / indicator type 300 flow and related configuration paths.

---

12. Fazit

Der aktuelle Custom-CLI-Umfang des Systems besteht aus mindestens 18 projektspezifischen Commands. Für den operativen Betrieb sind besonders relevant:

• mto:agent:ingest:run
• mto:agent:system:rebuild
• mto:agent:vector:control
• mto:agent:vector:health
• mto:agent:tags:rebuild
• mto:agent:tag:health