entity new

Legt eine neue Entität in einem Vault an. Die Form, in der Apparat im Alltag am häufigsten benutzt wird.

Interaktiv — der Normalfall

apparat entity new

Apparat fragt dich durch sechs Schritte:

1. Entity type — was für ein Ding legst du an? (person, project, concept, article, interview …)

Autocomplete auf die Typen, die es im Vault schon gibt. Du kannst bestehende übernehmen oder einen neuen englischen, klein­geschriebenen Singular-Typ vergeben. Wenn deine Eingabe einer bestehenden nahe kommt (z.B. Person statt person, oder WCAG statt wcag), bekommst du eine Rückfrage, ob du die kanonische Schreibweise übernehmen willst.

Auch wenn deine Eingabe nicht exakt einer bekannten Schreibweise entspricht, prüft Apparat sie auf Tippfehler und Buchstaben­dreher gegen die existierenden Typen. Findet sich etwas Ähnliches, bekommst du eine Auswahl: deinen Wert übernehmen oder den bestehenden vorschlagen. Im nicht-interaktiven Modus (etwa in Skripten) erscheint dasselbe als kurze Hinweis­zeile — dein Wert wird übernommen, dein Skript läuft durch. Dieselbe Logik wirkt weiter unten bei der Tag-Eingabe. Eine Übersicht aller Ähnlichkeits-Verfahren liegt in den Grundbegriffen.

2. Title (optional) — die Anzeigeform der Notiz.

Darf leer bleiben. Wenn leer, verwendet Apparat später die erste H1 im Body als Titel; gibt es keine, einen humanisierten Slug aus dem Dateinamen.

Wenn du einen Titel angibst, landet er zwei­fach: als title-Feld im Frontmatter (für die Anzeige und Index-Suche) und als # <titel>-Überschrift am Anfang des Body (damit die Datei auch in einem rohen Markdown-Renderer lesbar ist). Details im Abschnitt Titel und Überschrift im Body weiter unten.

3. Created — das Anlagedatum.

Wird implizit auf heute gesetzt (in der App-Zeitzone), kein interaktiver Schritt. Wenn du ein anderes Datum willst, gib es als --created mit.

4. Document language — die Hauptsprache des Dokuments.

Autocomplete auf die im Vault bereits verwendeten Sprachen. Der konfigurierte Default (APPARAT_DEFAULT_LANGUAGE, Shipping-Default de) ist vorausgewählt — Enter übernimmt ihn. Gültige Formen: de, en, fr, optional mit Region (de-DE, en-GB). Canonicalisation wie bei Typen: DE wird zu de, de-de zu de-DE, wenn das im Vault schon existiert.

5. Tags (optional) — kommagetrennt.

Hinweis auf bestehende Tags wird angezeigt. Gleiche Canonicalisation-Logik wie beim Typ: WCAG wird zu wcag, wenn das bereits so im Vault existiert.

6. Body — wie willst du den Fließtext schreiben?

Drei Varianten:

Titel und Überschrift im Body

Apparat schreibt den Titel per Default als H1 in den Body. Die Spur dahinter: eine Markdown-Datei wirkt ohne sichtbare Überschrift unfertig, wenn ein externer Renderer (GitHub, Texteditor-Preview) das Frontmatter ausblendet — die H1 im Body macht die Notiz für jedes Markdown-Tool lesbar.

Die Regel greift in allen Eingabewegen:

Nach dem Speichern erscheint die Bestätigung mit dem Dateipfad:

Created entity V1StGXRa in vault "recherche".
  File: /home/max/projects/apparat/vaults/recherche/content/2026-04-21--maria-beispiel--V1StGXRa.md

Nicht-interaktiv — für Skripte

Im nicht-interaktiven Modus müssen alle Eingaben über Flags kommen:

apparat entity new person \
  --title="Maria Beispiel" \
  --language=de \
  --tag=kollegin --tag=wcag \
  --created=2026-04-19 \
  --body="# Maria Beispiel\n\nGespräch am Mittwoch." \
  --no-interaction

Anhänge — Assets direkt beim Anlegen

Oft hat eine Entität einen primären Inhalt, der als Datei vorliegt: eine Audio-Aufnahme eines Interviews, ein gescannter Brief, ein Buch-Exzerpt als PDF. Solche Anhänge übergibst du direkt beim Anlegen:

apparat entity new interview \
  --title="Gespräch mit Max über WCAG" \
  --attach=~/aufnahmen/2026-04-21-max.mp3 \
  --attach=~/aufnahmen/2026-04-21-max.txt \
  --no-interaction

Für jede --attach-Datei passiert dabei:

  1. Apparat kopiert die Datei nach assets/ und benennt sie auf das Schema YYYY-MM-DD--slug--nanoid.ext um. Das Datum ist der Import­zeitpunkt, der Slug wird aus dem Original-Dateinamen abgeleitet, die NanoID wird frisch vergeben.
  2. Im Frontmatter landet ein Eintrag unter representations mit path und format (aus der Dateiendung erschlossener MIME-Typ).
  3. Die Reihen­folge der --attach-Argumente bestimmt die Reihen­folge im representations-Array. Der erste Eintrag gilt als „primärste" Repräsentation.

Kopieren vs. verschieben

Standard­mäßig kopiert Apparat die Quell­datei: dein Original bleibt da, wo es war. Mit --move wird die Quelle nach dem erfolgreichen Import gelöscht — nützlich beim Import aus einem Download-Ordner:

apparat entity new document \
  --title="Finanzamt-Bescheid 2025" \
  --attach=~/Downloads/finanzamt-2025.pdf \
  --move \
  --no-interaction

Das --move-Flag wirkt auf alle --attach-Dateien eines Aufrufs.

MIME-Typ und Dateiendung

Das format-Feld in representations wird automatisch aus der Datei­endung erschlossen (z.B. .mp3 → audio/mpeg, .pdf → application/pdf). Für unbekannte Endungen trägt Apparat application/octet-stream ein — du kannst den Wert nachträglich über entity meta anpassen.

Externe Verweise

Manchmal lebt der Primär­inhalt außerhalb des Vaults — ein Vortrag auf YouTube, ein Artikel auf einer Nachrichten­seite. Statt die Ressource lokal zu kopieren, hinterlegst du nur einen Verweis:

apparat entity new video \
  --title="Vortrag 'Kontrast neu gedacht'" \
  --external=https://conference.example.com/2025/kontrast-neu-gedacht \
  --no-interaction

Pro --external-URL entsteht ein Eintrag unter dem Frontmatter-Feld external mit url, format und title. Ohne weitere Angaben verwendet Apparat text/html als Format und die URL selbst als Titel — beides lässt sich später über entity meta verfeinern. Apparat lädt nichts herunter; externe Ressourcen bleiben extern.

--attach und --external dürfen in demselben Aufruf gemischt werden.

Body aus der Pipe

Wenn du die Notiz aus einer anderen Quelle hast, funktioniert auch:

echo "# Kurznotiz\n\nBody-Text." | apparat entity new gedanke --title=Kurznotiz --no-interaction

cat ~/recherche/max-mustermann.md | apparat entity new person --title="Max Mustermann" --no-interaction

Stdin wird nur im nicht-interaktiven Modus als Body-Quelle verwendet — im interaktiven Modus würde das den Body-Wahl-Prompt umgehen und wäre verwirrend.

Vault wählen

Wenn du mehrere Vaults hast, sagst du Apparat, welcher gemeint ist:

apparat entity new person --vault=arbeit
apparat entity new person --vault=https://apparat.example.com/vaults/arbeit
apparat entity new person --vault=/home/max/vaults/arbeit

Ohne --vault:

Was landet auf der Festplatte?

Eine neue Datei in content/ mit dem Schema YYYY-MM-DD--slug--nanoid.md:

vaults/recherche/content/2026-04-21--maria-beispiel--V1StGXRa.md

Inhalt:

---
id: V1StGXRa
type: person
created: 2026-04-21
language: de
updated: '2026-04-21T10:14:02+02:00'
title: Maria Beispiel
tags:
  - kollegin
  - wcag
---

# Maria Beispiel

Gespräch am Mittwoch.

Das updated-Feld setzt Apparat automatisch beim Schreiben — du kümmerst dich nicht darum. Bei Neuanlage entspricht es dem Anlagezeitpunkt. Spätere Editor-Kommandos werden den Wert bei jeder Änderung überschreiben.

Das Schreiben passiert atomar: Apparat schreibt zuerst in eine temporäre Datei und benennt sie dann auf den Ziel­namen um. Ein Crash mitten im Vorgang hinterlässt nie eine halbgeschriebene Datei.

Fehler