CLI-Referenz

Die EmDash CLI bietet Befehle zur Verwaltung einer EmDash CMS-Instanz — Datenbank-Setup, Typgenerierung, Inhalts-CRUD, Schema-Verwaltung, Medien und mehr.

Installation

Die CLI ist im emdash-Paket enthalten. Installiere sie mit folgendem Befehl:

npm install emdash

Führe Befehle mit npx emdash aus oder füge Skripte zu package.json hinzu. Die Binärdatei ist auch als em für Kürze verfügbar.

Authentifizierung

Befehle, die den gemeinsamen Remote-Client verwenden, lösen die Authentifizierung in dieser Reihenfolge auf:

1. --token-Flag — expliziter Token auf der Kommandozeile
2. EMDASH_TOKEN-Umgebungsvariable
3. Gespeicherte Anmeldedaten aus ~/.config/emdash/auth.json (gespeichert durch emdash login)
4. Dev-Bypass — wenn die URL localhost ist und kein Token verfügbar ist, wird automatisch über den Dev-Bypass-Endpunkt authentifiziert

Diese Befehle akzeptieren --url (von EMDASH_URL, Fallback auf http://localhost:4321) und --token-Flags. Authentifizierungsbefehle haben eigene Verbindungsoptionen. Wenn du einen lokalen Dev-Server ansteuerst, ist kein Token nötig.

Allgemeine Flags

Diese Flags sind bei Befehlen verfügbar, die den gemeinsamen Remote-Client verwenden:

Ausgabe

Wenn stdout ein TTY ist, gibt die CLI Ergebnisse hübsch formatiert mit consola aus. Wenn gepipt oder wenn --json gesetzt ist, gibt sie rohes JSON an stdout aus — geeignet für jq oder andere Tools.

Befehle

emdash dev

Starte den Entwicklungsserver mit automatischem Datenbank-Setup.

npx emdash dev [options]

Optionen

Beispiele

# Dev-Server starten
npx emdash dev

# Benutzerdefinierter Port
npx emdash dev --port 3000

# Typen vom Remote vor dem Start generieren
npx emdash dev --types

Verhalten

1. Prüft auf und führt ausstehende Datenbankmigrationen aus
2. Wenn --types gesetzt ist, generiert TypeScript-Typen von einer Remote-Instanz (URL aus EMDASH_URL-Env oder emdash.url in package.json)
3. Startet den Astro-Dev-Server mit gesetztem EMDASH_DATABASE_URL

emdash types

Generiere TypeScript-Typen aus dem Schema einer laufenden EmDash-Instanz.

npx emdash types [options]

Optionen

Beispiele

# Typen vom lokalen Dev-Server generieren
npx emdash types

# Vom Remote-Instanz generieren
npx emdash types --url https://my-site.pages.dev

# Benutzerdefinierter Ausgabepfad
npx emdash types --output src/types/emdash.ts

Verhalten

1. Holt das Schema von der Instanz
2. Generiert TypeScript-Typdefinitionen
3. Schreibt Typen in die Ausgabedatei
4. Schreibt daneben eine schema.json als Referenz

emdash login

Melde dich bei einer EmDash-Instanz mit OAuth Device Flow an.

npx emdash login [options]

Optionen

Verhalten

1. Entdeckt Auth-Endpunkte der Instanz
2. Wenn localhost und keine Auth konfiguriert, wird automatisch Dev-Bypass verwendet
3. Ansonsten wird OAuth Device Flow initiiert — zeigt einen Code an und öffnet den Browser
4. Pollt auf Autorisierung, speichert dann Anmeldedaten in ~/.config/emdash/auth.json

Gespeicherte Anmeldedaten werden automatisch von allen nachfolgenden Befehlen verwendet, die dieselbe Instanz ansprechen.

emdash logout

Abmelden und gespeicherte Anmeldedaten entfernen.

npx emdash logout [options]

Optionen

emdash whoami

Zeige den aktuell authentifizierten Benutzer.

npx emdash whoami [options]

Optionen

Zeigt E-Mail, Name, Rolle, Auth-Methode und Instanz-URL an.

emdash content

Inhalte verwalten. Alle Unterbefehle verwenden die Remote-API über EmDashClient.

content list <collection>

npx emdash content list posts
npx emdash content list posts --status published --limit 10

content get <collection> <id>

npx emdash content get posts 01ABC123
npx emdash content get posts 01ABC123 --raw

Die Antwort enthält ein _rev-Token. Übergib es an content update, um zu bestätigen, dass du den aktuellen Stand gesehen hast, bevor du überschreibst.

content create <collection>

npx emdash content create posts --data '{"title": "Hello"}'
npx emdash content create posts --file post.json --slug hello-world
cat post.json | npx emdash content create posts --stdin

Stelle Daten über genau eine der Optionen --data, --file oder --stdin bereit. Neue Einträge werden automatisch veröffentlicht, es sei denn --draft ist gesetzt.

content update <collection> <id>

Du musst das _rev-Token aus einem vorherigen get angeben, um zu beweisen, dass du den aktuellen Stand gesehen hast. Dies verhindert das Überschreiben von Änderungen, die du nicht gesehen hast. Die folgenden Schritte lesen einen Eintrag und aktualisieren ihn dann mit diesem Token:

# 1. Eintrag lesen, _rev notieren
npx emdash content get posts 01ABC123

# 2. Mit _rev aus Schritt 1 aktualisieren
npx emdash content update posts 01ABC123 \
  --rev MToyMDI2LTAyLTE0... \
  --data '{"title": "Aktualisiert"}'

Wenn sich der Eintrag seit deinem get geändert hat, gibt der Server 409 Conflict zurück — erneut lesen und nochmal versuchen.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Soft-Delete des Inhaltseintrags (in den Papierkorb verschoben).

content publish <collection> <id>

npx emdash content publish posts 01ABC123

content unpublish <collection> <id>

npx emdash content unpublish posts 01ABC123

content schedule <collection> <id>

npx emdash content schedule posts 01ABC123 --at 2026-03-01T09:00:00Z

content restore <collection> <id>

npx emdash content restore posts 01ABC123

Stellt einen gelöschten Inhaltseintrag wieder her.

emdash schema

Sammlungen und Felder verwalten.

schema list

npx emdash schema list

Listet alle Sammlungen auf.

schema get <collection>

npx emdash schema get posts

Zeigt eine Sammlung mit allen Feldern.

schema create <collection>

npx emdash schema create articles --label Articles
npx emdash schema create articles --label Articles --label-singular Article --description "Blog-Artikel"

schema delete <collection>

npx emdash schema delete articles
npx emdash schema delete articles --force

Fragt nach Bestätigung, es sei denn --force ist gesetzt.

schema add-field <collection> <field>

npx emdash schema add-field posts body --type portableText --label "Textinhalt"
npx emdash schema add-field posts featured --type boolean --required

schema remove-field <collection> <field>

npx emdash schema remove-field posts featured

emdash media

Medien verwalten.

media list

npx emdash media list
npx emdash media list --mime image/png --limit 20

media upload <file>

npx emdash media upload ./photo.jpg
npx emdash media upload ./photo.jpg --alt "Ein Sonnenuntergang" --caption "Aufgenommen in Bristol"

media get <id>

npx emdash media get 01MEDIA123

media delete <id>

npx emdash media delete 01MEDIA123

media repair-usage

Repariere Medienverwendungsindizes für eine Sammlung oder für alle Inhaltssammlungen. Verwende dies nach Importen oder direkten Datenbankschreibvorgängen, wenn die Verwendungsabdeckung veraltet oder nicht vertrauenswürdig ist.

npx emdash media repair-usage --collection posts
npx emdash media repair-usage --all
npx emdash media repair-usage --all --json

Übergib genau eine der Optionen --collection oder --all. Remote-Reparatur erfordert einen Admin-Benutzer und ein Auth-Token mit dem admin-Scope.

Die Reparatur aller Inhalte läuft synchron und kann auf großen Sites langsam oder teuer sein. Bevorzuge --collection, wenn du nur eine Sammlung reparieren musst.

Strukturierte Reparaturergebnisse complete, partial und stale beenden mit 0; strukturierte failed-Ergebnisse mit 1. Automatisierung und Cron-Jobs sollten --json verwenden und status, failedSourceCount, skippedSourceCount und Zusammenfassungen pro Sammlung parsen, anstatt Exit 0 als vollständige Abdeckung zu behandeln.

emdash search

Volltextsuche über Inhalte.

npx emdash search "hello world"
npx emdash search "hello" --collection posts --limit 5

emdash taxonomy

Taxonomien und Begriffe verwalten.

taxonomy list

npx emdash taxonomy list

taxonomy terms <name>

npx emdash taxonomy terms categories
npx emdash taxonomy terms tags --limit 50

taxonomy add-term <taxonomy>

npx emdash taxonomy add-term categories --name "Tech" --slug tech
npx emdash taxonomy add-term categories --name "Frontend" --parent 01PARENT123

emdash menu

Navigationsmenüs verwalten.

menu list

npx emdash menu list

menu get <name>

npx emdash menu get primary

Gibt das Menü mit allen Elementen zurück.

emdash export-seed

Datenbankschema und Inhalte als Seed-Datei exportieren. Arbeitet direkt mit einer lokalen SQLite-Datei.

npx emdash export-seed [options] > seed.json

Optionen

Ausgabeformat

Die exportierte Seed-Datei enthält:

• Einstellungen: Seitentitel, Untertitel, Social Links
• Sammlungen: Alle Sammlungsdefinitionen mit Feldern
• Taxonomien: Taxonomie-Definitionen und Begriffe
• Menüs: Navigationsmenüs mit Elementen
• Widget-Bereiche: Widget-Bereiche und Widgets
• Inhalte (wenn angefordert): Einträge mit $media-Referenzen und $ref:-Syntax für Portabilität

emdash secrets generate

Generiere einen EMDASH_ENCRYPTION_KEY für dein Deployment. Der Schlüssel wird verwendet, um Plugin-Geheimnisse im Ruhezustand zu verschlüsseln.

npx emdash secrets generate

Gibt den neuen Schlüssel auf stdout aus. Leite ihn in deinen Geheimnis-Speicher weiter, oder schreibe ihn direkt in deine lokale .env-Datei mit --write. Dieselbe .env-Datei wird von Node und in der lokalen Entwicklung von Wrangler und dem Cloudflare-Vite-Plugin gelesen:

npx emdash secrets generate --write .env

--write verweigert das Überschreiben eines vorhandenen Eintrags ohne --force. Das Ersetzen eines Schlüssels in einem Deployment mit vorhandenen verschlüsselten Daten macht diese Geheimnisse unlesbar, daher ist der Schutz beabsichtigt.

emdash secrets fingerprint <key>

Gib den 8-Zeichen-Fingerprint (kid) eines Schlüssels aus, ohne seinen Wert preiszugeben. Dies ist nützlich in CI, um zu überprüfen, ob der richtige Schlüssel deployed wurde. Der folgende Befehl gibt den Fingerprint eines Schlüssels aus:

npx emdash secrets fingerprint emdash_enc_v1_...

Generierte Dateien

.emdash/types.ts

Der Befehl emdash types generiert TypeScript-Interfaces für jede Sammlung:

// Generiert von der EmDash CLI
// Nicht manuell bearbeiten - führe `emdash types` aus, um neu zu generieren

import type { PortableTextBlock } from "emdash";

export interface Post {
	id: string;
	title: string;
	content: PortableTextBlock[];
	publishedAt: Date | null;
}

.emdash/schema.json

Der Befehl schreibt auch einen rohen Schema-Export für Tooling:

{
  "version": "a1b2c3d4",
  "collections": [
    {
      "slug": "posts",
      "label": "Posts",
      "fields": [...]
    }
  ]
}

Umgebungsvariablen

Package-Skripte

Füge die CLI-Befehle als package.json-Skripte für Komfort hinzu:

{
	"scripts": {
		"dev": "emdash dev",
		"types": "emdash types",
		"export-seed": "emdash export-seed",
		"db:reset": "rm -f data.db"
	}
}

Exit-Codes