Das apparat-Kommando

Apparat wird über das apparat-Kommando gesteuert. Du rufst es im Projektverzeichnis oder global (wenn verlinkt) auf.

Aufruf-Varianten

Die natürliche Form schreibt sich wie ein Befehl:

apparat vault init recherche
apparat entity new person --title="Maria Beispiel"

Diese Zwei-Wort-Form ist die, die du dir merken willst.

Hilfe zu einem Kommando

apparat help vault init
apparat help entity new

zeigt Argumente, Optionen und Standard­werte für das jeweilige Kommando. Das ist die maschinenlesbare Referenz; dieses Handbuch ergänzt sie um Beispiele und Kontext.

Übersicht der verfügbaren Kommandos

Die Kommandos sind nach Namespace gegliedert — jeder Namespace hat eine eigene Übersichts­seite, von der aus du zu den einzelnen Unter­kommandos navigierst.

vault — Vault-Verwaltung:

• vault init — einen neuen Vault anlegen
• vault validate — einen Vault gegen die Spec prüfen (Exit-Codes 0/1/2, optional --json)
• vault repair — den mechanisch sicher reparierbaren Teil der Befunde beheben (--dry-run für einen Trockenlauf)
• vault scan — Sammlungen im Hintergrund prüfen; speist den Web-Hinweis auf strukturelle Probleme
• vault trash list — den Trash eines Vaults auflisten
• vault trash restore — eine soft-gelöschte Entität zurückholen
• vault trash empty — einen oder alle Trash-Einträge endgültig entfernen

entity — Entitäten:

• entity new — eine neue Entität anlegen (interaktiv oder per Flags)
• entity list — Entitäten eines Vaults tabellarisch auflisten
• entity search — Volltextsuche (Standard), Bedeutungssuche (--semantic) oder kombinierte Suche (--hybrid)
• entity similar — Entitäten finden, deren Embedding einer Referenz-NanoId am nächsten liegt
• entity rename — Titel und Slug ändern; Dateiname folgt, NanoID bleibt stabil
• entity edit — den Fließtext bearbeiten; Frontmatter bleibt unberührt
• entity meta — Frontmatter bearbeiten (Walkthrough, Flags oder YAML-Editor); Body bleibt unberührt
• entity delete — eine Entität per Soft-Delete in den Trash verschieben

asset — Asset-Dateien:

• asset embed — eine Datei in assets/ importieren und die fertige Markdown-Einbettung (![alt](pfad)) auf stdout ausgeben
• asset rename — den Slug einer Asset-Datei ändern; alle Referenzen in Entitäten werden mitgezogen

graph — Beziehungs-Graph:

• graph rebuild — den Graph eines Vaults aus den Markdown-Dateien komplett neu aufbauen
• graph watch — Dateibeobachtung, die den Graph laufend aktuell hält
• graph stats — Zahlen und Verteilungen (Entitäten, Assets, Beziehungen, Dateigröße)

vector — Semantische Suche:

• vector ping — prüft, ob der Embedding-Dienst erreichbar ist und das Modell geladen hat
• vector stats — Zähler, Modell, Abdeckung und Dateigröße des Vektor-Index
• vector drift — Entitäten ohne aktuelles Embedding (Backlog für den Hintergrund-Worker)
• vector rebuild — den Vektor-Index inkrementell oder vollständig neu aufbauen

ner — Schreibassistenz:

• ner ping — prüft, ob der Sprach­erkennungs-Dienst erreichbar ist
• ner suggest — startet eine Vorschlagsrunde für eine Entität (Personen, Orte, Organisationen aus dem Body, gegen den Vault abgeglichen)

consolidate — Vokabular-Konsolidierung:

• consolidate type — listet existierende Typen, die einem Kandidaten ähneln
• consolidate relation — Pendant für Beziehungs­namen

chat — Dialog mit dem Vault:

• chat ping — prüft, ob der Sprachmodell-Dienst erreichbar ist und das Modell geladen hat
• chat start — eine neue Konversation interaktiv eröffnen
• chat continue — eine bestehende Konversation interaktiv fortsetzen
• chat ask — einen einzelnen Turn anhängen, ohne Prompt-Loop (skript-tauglich)
• chat list — Konversationen des Vaults nach jüngster Aktivität sortieren
• chat show — Header und Verlauf einer Konversation anzeigen
• chat export — den ganzen Dialog als conversation-Notiz in den Vault schreiben
• chat synthesize — eine einzelne Antwort als eigenständige Notiz übernehmen
• chat retitle — den Titel einer Konversation per Sprachmodell-Pass neu vergeben
• chat delete — eine Konversation samt Turns aus dem Speicher entfernen

llm — Inferenz-Backend:

• llm mode — das Backend für Bedeutungssuche und Dialog zwischen lokal und einem Remote-Host umschalten (oder den aktiven Modus anzeigen)

octane — Web-Oberfläche:

• octane status — sagt in einer Zeile, ob die Web-Oberfläche gerade läuft

user — Account-Verwaltung:

• user create — Operator-Account für die Web-Oberfläche anlegen (oder mit --force überschreiben)

Mandanten-Ergonomie:

• shell — interaktive Sitzung, an einen Mandanten und eine Sammlung gebunden; Kommandos ohne apparat-Präfix
• tenant — zeigt den aktuell aufgelösten Mandanten und listet die bekannten Mandanten

Mehr zur Architektur und Roadmap.

Installation

Per Default liegt das apparat-Kommando im Projektverzeichnis und du rufst es als ./apparat auf. Für globale Nutzung gibt es zwei Wege:

Symlink nach /usr/local/bin/ (empfohlen):

sudo ln -s "$(pwd)/apparat" /usr/local/bin/apparat

Per PATH-Variable:

echo "export PATH=\"$(pwd):\$PATH\"" >> ~/.bashrc

Beide Varianten erlauben dir anschließend, apparat aus beliebigen Verzeichnissen heraus aufzurufen — das Kommando findet artisan über seinen eigenen Skript-Pfad, nicht über getcwd().

Container-Kommandos werden automatisch im Container ausgeführt

In einer Mehrmandanten-Installation liegen die Sammlungen eines Mandanten im Web-Container dieses Mandanten. Deshalb führt das apparat-Kommando praktisch jeden Aufruf, der eine Sammlung berührt, automatisch dort aus — du tippst auf dem Host, gearbeitet wird im Container. Das gilt für die alltäglichen Sammlungs-Kommandos wie entity new, entity list oder vault validate ebenso wie für die, die ohnehin einen nur dort laufenden Dienst brauchen: den Embedding-Dienst (Bedeutungssuche), den Sprach­erkennungs-Dienst, das Sprach­modell für den Chat und die Datei­beobachtung.

Auf dem Host bleiben allein die Kommandos, die die Installation als Ganzes oder über Mandanten hinweg verwalten — das Einrichten, das Anlegen und Abgleichen von Mandanten und der Umgebungs-Abgleich. Sie würden in einem einzelnen Mandanten-Container keinen Sinn ergeben.

Du tippst also schlicht

apparat entity list --vault=recherche
apparat entity search "barrierefreie formulare" --semantic

und musst dich um Container-Details nicht selbst kümmern. Voraussetzung ist, dass der Container läuft (docker compose up -d); fehlt er, bricht das Kommando mit einer entsprechenden Fehlermeldung ab. Auf einer Einzel-Installation ohne eigene Mandanten gilt dasselbe Prinzip mit dem mitgelieferten Web-Container.

Vier Hinweise im Detail:

• Mandanten-Wahl: Welcher Mandant das Ziel ist, bestimmt --tenant=<name> bzw. die APPARAT_TENANT-Umgebungsvariable; existiert genau ein Mandant, wird er automatisch erkannt — du brauchst dann kein Flag. Welcher Mandant gerade aufgelöst wird, zeigt dir apparat tenant. Mandanten-übergreifende Aufgaben laufen ohnehin host-lokal.
• Vault-Argumente: Der registrierte Vault-Name (--vault=recherche) und die Auto-Erkennung aus dem aktuellen Verzeichnis funktionieren über die Delegation hinweg. Auch ein Host-Pfad innerhalb deines Vault-Verzeichnisses wird automatisch in den passenden Container-Pfad übersetzt; ein Pfad außerhalb davon bleibt unverändert — dann nimmst du den Vault-Namen oder erzwingst den Host-Lauf über --no-docker.
• --no-docker ist die Debug-Eskape: damit läuft das Kommando lokal auf dem Host statt im Container — nützlich zum Reproduzieren von Fehlern oder wenn die nötigen Dienste direkt auf dem Host installiert sind. Ein Hinweis weist dich darauf hin, dass der Host die Sammlung des Mandanten dabei womöglich nicht findet.
• Im Container selbst läuft die Delegation nicht — Apparat erkennt das und führt das Kommando direkt aus.

Mehrere Mandanten und die Mandanten-Wahl

Eine Apparat-Installation kann mehrere Mandanten beherbergen — etwa eine eigene Umgebung je Domain, jede mit ihren eigenen Sammlungen und ihrem eigenen Login. Auf einer gewöhnlichen Einzel-Installation gibt es genau einen Mandanten; dann brauchst du dich um die Mandanten-Wahl nicht zu kümmern, alles wird automatisch erkannt.

Sobald ein Kommando in den Container delegiert wird, muss feststehen, welcher Mandant gemeint ist. Die Reihenfolge:

1. --tenant=<name> am einzelnen Aufruf,
2. die Umgebungsvariable APPARAT_TENANT,
3. automatische Erkennung, wenn es nur einen Mandanten gibt.

Welcher Mandant daraus resultiert — und woher die Wahl stammt —, zeigt dir ein einzelner Befehl:

apparat tenant

Er listet die bekannten Mandanten und nennt den aktuell aufgelösten samt Quelle (Flag, Umgebungsvariable oder automatische Erkennung). Lässt sich kein eindeutiger Mandant bestimmen, sagt er das ebenfalls — dann hilft --tenant=<name>.

Für längeres Arbeiten in einem Mandanten lohnt die interaktive Shell: Sie bindet Mandant und Sammlung einmal und nimmt danach präfixfreie Kommandos entgegen.

Das Einrichten eines neuen Mandanten gehört zur Server-Installation und ist daher nicht Teil des täglichen Arbeitens mit dem apparat-Kommando.

Nicht-interaktiver Modus

Jedes Kommando, das normalerweise interaktive Rückfragen stellt (z.B. entity new), akzeptiert die Option --no-interaction. In dieser Betriebsart fehlt jede Rückfrage — du musst alle benötigten Werte als Flags mitgeben, sonst bricht das Kommando mit einer Fehlermeldung ab. Das ist praktisch für Skripte und CI-Pipelines:

apparat entity new person \
  --title="Maria Beispiel" \
  --tag=wcag --tag=kollegin \
  --body-file=/tmp/notiz.md \
  --no-interaction

Stdin wird in diesem Modus als Body-Quelle akzeptiert, falls weder --body noch --body-file gesetzt ist — cat notiz.md | apparat entity new person --title=X --no-interaction funktioniert also auch.

Exit-Codes

Apparat-Kommandos halten sich an die POSIX-Konvention: