CLI-Referenz

Die EmDash CLI bietet Befehle zur Verwaltung einer EmDash CMS-Instanz — Datenbankeinrichtung, Typ-Generierung, Content-CRUD, Schema-Verwaltung, Medien und mehr.

Installation

Die CLI ist im emdash-Paket enthalten. Installieren Sie es mit dem folgenden Befehl:

npm install emdash

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

Authentifizierung

Befehle, die mit einer laufenden EmDash-Instanz kommunizieren, lösen die Authentifizierung in dieser Reihenfolge auf:

1. --token-Flag — explizites Token in der Befehlszeile
2. EMDASH_TOKEN Umgebungsvariable
3. Gespeicherte Anmeldedaten aus ~/.config/emdash/auth.json (gespeichert durch emdash login)
4. Entwickler-Bypass — wenn die URL localhost ist und kein Token verfügbar ist, erfolgt die Authentifizierung automatisch über den Entwickler-Bypass-Endpunkt

Die meisten Befehle akzeptieren --url (Standard http://localhost:4321) und --token Flags. Wenn ein lokaler Entwicklungsserver angesprochen wird, wird kein Token benötigt.

Häufige Flags

Diese Flags sind bei allen Remote-Befehlen verfügbar:

Ausgabe

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

Befehle

emdash dev

Startet den Entwicklungsserver mit automatischer Datenbankeinrichtung.

npx emdash dev [options]

Optionen

Beispiele

# Entwicklungsserver starten
npx emdash dev

# Benutzerdefinierter Port
npx emdash dev --port 3000

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

Verhalten

1. Überprüft und führt ausstehende Datenbankmigrationen aus
2. Wenn --types gesetzt ist, werden TypeScript-Typen aus einer Remote-Instanz generiert (URL aus EMDASH_URL env oder emdash.url in package.json)
3. Startet Astro-Entwicklungsserver mit gesetzter EMDASH_DATABASE_URL

emdash types

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

npx emdash types [options]

Optionen

Beispiele

# Typen von lokalem Entwicklungsserver generieren
npx emdash types

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

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

Verhalten

1. Ruft das Schema von der Instanz ab
2. Generiert TypeScript-Typ-Definitionen
3. Schreibt Typen in die Ausgabedatei
4. Schreibt schema.json daneben als Referenz

emdash login

Melden Sie sich bei einer EmDash-Instanz mit OAuth Device Flow an.

npx emdash login [options]

Optionen

Verhalten

1. Entdeckt Authentifizierungs-Endpunkte von der Instanz
2. Wenn localhost und keine Authentifizierung konfiguriert ist, verwendet automatisch Entwickler-Bypass
3. Andernfalls initiiert OAuth Device Flow — zeigt einen Code an und öffnet Ihren Browser
4. Fragt Autorisierung ab und speichert dann Anmeldedaten in ~/.config/emdash/auth.json

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

emdash logout

Abmelden und gespeicherte Anmeldedaten entfernen.

npx emdash logout [options]

Optionen

emdash whoami

Zeigt den aktuell authentifizierten Benutzer an.

npx emdash whoami [options]

Optionen

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

emdash content

Verwaltet Inhaltselemente. 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. Übergeben Sie es an content update, um zu bestätigen, dass Sie den aktuellen Zustand gesehen haben, bevor Sie ihn überschreiben.

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

Geben Sie Daten über genau eine der Optionen --data, --file oder --stdin an. Neue Elemente werden automatisch veröffentlicht, es sei denn, --draft ist gesetzt.

content update <collection> <id>

Sie müssen das _rev-Token von einem vorherigen get angeben, um zu beweisen, dass Sie den aktuellen Zustand gesehen haben. Dies verhindert, dass Änderungen überschrieben werden, die Sie nicht gesehen haben. Die folgenden Schritte lesen ein Element und aktualisieren es dann mit diesem Token:

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

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

Wenn sich das Element seit Ihrem get geändert hat, gibt der Server 409 Conflict zurück — erneut lesen und erneut versuchen.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Löscht das Inhaltselement soft (verschiebt in den Papierkorb).

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 ein gelöschtes Inhaltselement wieder her.

emdash schema

Verwaltet Sammlungen und Felder.

schema list

npx emdash schema list

Listet alle Sammlungen auf.

schema get <collection>

npx emdash schema get posts

Zeigt eine Sammlung mit all ihren Feldern an.

schema create <collection>

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

schema delete <collection>

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

Fordert zur Bestätigung auf, es sei denn, --force ist gesetzt.

schema add-field <collection> <field>

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

schema remove-field <collection> <field>

npx emdash schema remove-field posts featured

emdash media

Verwaltet Medienelemente.

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 "A sunset" --caption "Taken in Bristol"

media get <id>

npx emdash media get 01MEDIA123

media delete <id>

npx emdash media delete 01MEDIA123

emdash search

Volltextsuche über Inhalte.

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

emdash taxonomy

Verwaltet Taxonomien und Begriffe.

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

Verwaltet Navigationsmenüs.

menu list

npx emdash menu list

menu get <name>

npx emdash menu get primary

Gibt das Menü mit all seinen Elementen zurück.

emdash export-seed

Exportiert Datenbankschema und Inhalt als Seed-Datei. Funktioniert direkt mit einer lokalen SQLite-Datei.

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

Optionen

Ausgabeformat

Die exportierte Seed-Datei enthält:

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

emdash secrets generate

Generiert einen EMDASH_ENCRYPTION_KEY für Ihre Bereitstellung. Der Schlüssel wird verwendet, um Plugin-Geheimnisse im Ruhezustand zu verschlüsseln.

npx emdash secrets generate

Gibt den neuen Schlüssel nach stdout aus. Leiten Sie ihn in Ihren Secret Store weiter oder schreiben Sie ihn direkt in eine Entwicklungsdatei mit --write. Die folgenden Befehle schreiben den Schlüssel in .dev.vars oder .env:

npx emdash secrets generate --write .dev.vars
npx emdash secrets generate --write .env

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

emdash secrets fingerprint <key>

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

npx emdash secrets fingerprint emdash_enc_v1_...

Generierte Dateien

.emdash/types.ts

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

// Generated by EmDash CLI
// Do not edit manually - run `emdash types` to regenerate

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 Tools:

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

Umgebungsvariablen

Package-Skripte

Fügen Sie die CLI-Befehle als package.json-Skripte zur Bequemlichkeit hinzu:

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

Exit-Codes