CLI-Referenz

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

Installation

Die CLI ist im emdash-Paket enthalten:

npm install emdash

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

Authentifizierung

Befehle, die mit einer laufenden EmDash-Instanz kommunizieren (alles außer init, seed, export-seed und auth secret), lösen die Authentifizierung in dieser Reihenfolge auf:

1. --token-Flag — expliziter Token in der Befehlszeile
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, erfolgt die Authentifizierung automatisch über den Dev-Bypass-Endpunkt

Die meisten Befehle akzeptieren die Flags --url (Standard http://localhost:4321) und --token. Wenn Sie einen lokalen Entwicklungsserver ansprechen, ist kein Token erforderlich.

Allgemeine Flags

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

Ausgabe

Wenn stdout ein TTY ist, gibt die CLI Ergebnisse mit consola formatiert aus. Beim Pipen oder wenn --json gesetzt ist, wird rohes JSON auf stdout ausgegeben — geeignet für jq oder andere Werkzeuge.

Befehle

emdash init

Initialisiert die Datenbank mit dem Kernschema und optionalen Vorlagendaten.

npx emdash init [options]

Optionen

Verhalten

1. Liest die emdash-Konfiguration aus package.json
2. Erstellt die Datenbankdatei bei Bedarf
3. Führt Kernmigrationen aus (erstellt Systemtabellen)
4. Führt die Vorlage schema.sql aus, falls konfiguriert
5. Führt die Vorlage seed.sql aus, falls konfiguriert

emdash dev

Startet den Entwicklungsserver mit automatischer Datenbankeinrichtung.

npx emdash dev [options]

Optionen

Beispiele

# Start dev server
npx emdash dev

# Custom port
npx emdash dev --port 3000

# Generate types from remote before starting
npx emdash dev --types

Verhalten

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

emdash types

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

npx emdash types [options]

Optionen

Beispiele

# Generate types from local dev server
npx emdash types

# Generate from remote instance
npx emdash types --url https://my-site.pages.dev

# Custom output path
npx emdash types --output src/types/emdash.ts

Verhalten

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

emdash login

Meldet Sie bei einer EmDash-Instanz über OAuth Device Flow an.

npx emdash login [options]

Optionen

Verhalten

1. Erkennt die Auth-Endpunkte der Instanz
2. Wenn localhost und keine Authentifizierung konfiguriert ist, wird automatisch der Dev-Bypass verwendet
3. Andernfalls wird der OAuth Device Flow gestartet — zeigt einen Code an und öffnet Ihren Browser
4. Wartet auf die Autorisierung und speichert dann die Anmeldedaten in ~/.config/emdash/auth.json

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

emdash logout

Meldet Sie ab und entfernt gespeicherte Anmeldedaten.

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 einen _rev-Token — übergeben Sie ihn an content update, um zu belegen, dass Sie den aktuellen Stand gesehen haben, den Sie ü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.

content update <collection> <id>

Wie ein Dateieditor, der erfordert, dass Sie vor dem Schreiben lesen — Sie müssen den _rev-Token aus einem vorherigen get angeben, um zu belegen, dass Sie den aktuellen Stand gesehen haben. Dies verhindert das versehentliche Überschreiben von Änderungen, die Sie nicht gesehen haben.

# 1. Read the item, note the _rev
npx emdash content get posts 01ABC123

# 2. Update with the _rev from step 1
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 — lesen Sie erneut und versuchen Sie es nochmals.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Löscht das Inhaltselement vorläufig (verschiebt es 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 eine Bestätigung an, 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 alle 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 Einträgen zurück.

emdash seed

Wendet eine Seed-Datei auf die Datenbank an. Dieser Befehl arbeitet direkt mit einer lokalen SQLite-Datei (kein laufender Server erforderlich).

npx emdash seed [path] [options]

Argumente

Optionen

Auflösung der Seed-Datei

Der Befehl sucht in dieser Reihenfolge nach Seed-Dateien:

1. Positionsargument (falls angegeben)
2. .emdash/seed.json (Konvention)
3. Pfad aus dem Feld emdash.seed in package.json

emdash export-seed

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

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

Optionen

Ausgabeformat

Die exportierte Seed-Datei enthält:

• Einstellungen: Seitentitel, Tagline, Social-Media-Links
• Sammlungen: Alle Sammlungsdefinitionen mit Feldern
• Taxonomien: Taxonomiedefinitionen und Begriffe
• Menüs: Navigationsmenüs mit Einträgen
• Widget-Bereiche: Widget-Bereiche und Widgets
• Inhalte (falls angefordert): Einträge mit $media-Referenzen und $ref:-Syntax für Portabilität

emdash auth secret

Generiert ein sicheres Authentifizierungsgeheimnis für Ihre Bereitstellung.

npx emdash auth secret

Gibt ein zufälliges Geheimnis aus, das für EMDASH_AUTH_SECRET geeignet ist.

Generierte Dateien

.emdash/types.ts

Von emdash types generierte TypeScript-Schnittstellen:

// 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

Roher Schema-Export für Werkzeuge:

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

Umgebungsvariablen

Paketskripte

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

Exit-Codes