Référence de la CLI

La CLI EmDash fournit des commandes pour la configuration de la base de données, la génération de types, la création et la modification de contenu, la gestion du schéma, les médias, l’export et l’import de site, ainsi que le développement de plugins.

Installation

La CLI est incluse avec le paquet emdash. Installez-la avec la commande suivante :

npm install emdash

Exécutez les commandes avec npx emdash ou ajoutez des scripts à package.json. Le binaire est aussi disponible sous em pour plus de brièveté.

Démarrez votre site avec son script de paquet, tel que pnpm dev. Le script de paquet démarre Astro ; l’intégration EmDash génère emdash-env.d.ts, tandis que le runtime exécute les migrations en attente à la première requête et applique le seed empaqueté lorsque la base de données est vide et que la configuration n’est pas terminée.

Authentification

Les commandes qui se connectent à une instance EmDash en cours d’exécution résolvent l’authentification dans cet ordre :

1. Flag --token — jeton explicite sur la ligne de commande
2. Variable d’environnement EMDASH_TOKEN
3. Identifiants stockés depuis ~/.config/emdash/auth.json (enregistrés par emdash login)
4. Dev bypass — si l’URL est localhost et qu’aucun jeton n’est disponible, authentification automatique via l’endpoint de dev bypass

Les commandes types, whoami, content, schema, media, search, taxonomy, menu et site se connectent à une instance en cours d’exécution. Les commandes d’authentification ont leurs propres options de connexion. Lorsqu’on cible un serveur de développement local, aucun jeton n’est nécessaire.

Flags communs

Les flags de connexion varient selon la commande. Les commandes groupées ci-dessous désignent chaque sous-commande de ce groupe.

Sortie

Lorsqu’une commande écrit des résultats dans un terminal interactif, elle les formate pour la lecture. Les commandes listées avec --json ci-dessus écrivent du JSON brut lorsque le flag est défini ou que leur sortie est pipée. emdash migrate émet du JSON uniquement avec son option explicite --json.

Commandes

emdash init

Initialise une base de données SQLite locale à partir des métadonnées de modèle dans package.json. La commande exécute les migrations principales, puis applique le fichier SQL optionnel nommé par emdash.schema. Exécutez emdash seed séparément pour les données seed JSON.

npx emdash init [options]

Sans --force, une base initialisée est laissée inchangée. Cette commande ouvre un fichier SQLite local directement ; utilisez emdash migrate pour les migrations D1, PostgreSQL, libSQL ou Hyperdrive gérées par le déploiement.

emdash doctor

Vérifie une base SQLite locale pour des problèmes de connexion, migration, collection, table et utilisateur. Si le projet a une configuration Wrangler, la commande vérifie aussi qu’un Cron Trigger et un gestionnaire EmDash scheduled() sont configurés ensemble.

npx emdash doctor [options]

La commande signale chaque vérification comme réussite, avertissement ou échec et se termine avec un code non nul lorsqu’une vérification échoue.

emdash seed

Valide ou applique un seed JSON à une base SQLite locale. La commande utilise le chemin positionnel s’il est fourni, puis .emdash/seed.json, puis le chemin emdash.seed de package.json.

npx emdash seed [path] [options]

L’application d’un seed exécute d’abord les migrations principales. Utilisez --validate en intégration continue lorsque vous devez vérifier le fichier sans ouvrir ni créer la base.

emdash migrate

Vérifie ou applique l’ensemble de migrations principales émis par une build Astro.

npx emdash migrate [options]
npx emdash migrate --check [options]
npx emdash migrate --status --json [options]
npx emdash migrate --release-lock <id> [options]

Par défaut, la commande découvre la racine du projet et lit .emdash/migrations.json. Elle valide le manifeste par rapport au paquet EmDash installé du projet, résout l’exécuteur local au projet de l’adaptateur et imprime la cible immuable avant tout SQL.

Options

L’application et la libération de verrou lisibles et interactives demandent confirmation. L’application ou la libération de verrou non interactive, et toute application ou libération de verrou avec --json, exigent l’empreinte exacte imprimée pour la cible. Il n’y a pas de down ni de --dry-run ; utilisez --check pour déterminer si du travail est requis.

Codes de sortie

Voir Manage Core Database Migrations pour l’ordre de déploiement, les identifiants de cible et le verrou de migration D1.

emdash dev (obsolète)

La commande legacy initialise et migre une base SQLite locale avant de démarrer Astro. Ce comportement n’utilise pas l’adaptateur de base configuré par le site et est incompatible avec le développement Cloudflare D1. Les invocations existantes affichent désormais un avertissement d’obsolescence avant tout travail sur la base.

emdash types

Génère des types TypeScript à partir du schéma d’une instance EmDash en cours d’exécution.

npx emdash types [options]

Options

Exemples

# 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

Comportement

1. Récupère le schéma depuis l’instance
2. Génère les définitions de types TypeScript
3. Écrit les types dans le fichier de sortie
4. Écrit schema.json à côté pour référence

emdash login

Se connecte à une instance EmDash via OAuth Device Flow.

npx emdash login [options]

Options

Comportement

1. Découvre les endpoints d’authentification depuis l’instance
2. Si localhost et aucune authentification configurée, utilise automatiquement le dev bypass
3. Sinon initie OAuth Device Flow — affiche un code et ouvre votre navigateur. Après saisie du code, la page d’administration liste les permissions que la CLI recevra, et toute permission demandée que votre rôle n’autorise pas, avant que vous n’approuviez.
4. Interroge l’autorisation, puis enregistre les identifiants dans ~/.config/emdash/auth.json

Les identifiants enregistrés sont utilisés automatiquement par toutes les commandes suivantes ciblant la même instance.

emdash logout

Se déconnecte et supprime les identifiants stockés.

npx emdash logout [options]

Options

emdash whoami

Affiche l’utilisateur authentifié actuel.

npx emdash whoami [options]

Options

Affiche l’e-mail, le nom, le rôle, la méthode d’authentification et l’URL de l’instance.

emdash content

Gère les éléments de contenu. Tous les sous-commandes utilisent l’API distante via 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

La réponse inclut un jeton _rev. Passez-le à content update pour confirmer que vous avez vu l’état actuel avant de l’écraser.

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

Fournissez les données via exactement l’un de --data, --file ou --stdin. Les nouveaux éléments sont publiés automatiquement sauf si --draft est défini.

content update <collection> <id>

Vous devez fournir le jeton _rev d’un get précédent pour prouver que vous avez vu l’état actuel. Cela empêche d’écraser des modifications que vous n’avez pas vues. Les étapes suivantes lisent un élément, puis le mettent à jour avec ce jeton :

# 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"}'

Si l’élément a changé depuis votre get, le serveur renvoie 409 Conflict — relisez et réessayez.

Si quelqu’un a l’entrée ouverte dans l’administration, le serveur renvoie 409 avec le code ENTRY_LOCKED et un message qui nomme le détenteur. Attendez qu’il ait fini, ou passez --override-lock. Le même flag est disponible sur content delete, content publish, content unpublish et content schedule.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Supprime soft l’élément de contenu (le déplace vers la corbeille).

Passez --override-lock pour supprimer une entrée qu’un autre éditeur a ouverte.

content publish <collection> <id>

npx emdash content publish posts 01ABC123

Passez --override-lock pour publier une entrée qu’un autre éditeur a ouverte.

content unpublish <collection> <id>

npx emdash content unpublish posts 01ABC123

Passez --override-lock pour dépublier une entrée qu’un autre éditeur a ouverte.

content schedule <collection> <id>

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

Passez --override-lock pour planifier une entrée qu’un autre éditeur a ouverte.

content restore <collection> <id>

npx emdash content restore posts 01ABC123

Restaure un élément de contenu mis à la corbeille.

content translations <collection> <id>

Liste chaque traduction du groupe de traduction de l’entrée :

npx emdash content translations posts 01ABC123

Le résultat inclut l’ID, la locale, le slug, le statut de chaque traduction et s’il s’agit de l’entrée demandée.

emdash schema

Gère les collections et les champs.

schema list

npx emdash schema list

Liste toutes les collections.

schema get <collection>

npx emdash schema get posts

Affiche une collection avec tous ses champs.

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

Demande confirmation sauf si --force est défini.

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

Gère les éléments multimédias.

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

media repair-usage

Répare les index d’utilisation des médias de contenu pour une collection ou pour chaque collection de contenu. Utilisez-le après des imports ou des écritures directes en base lorsque la couverture d’utilisation est obsolète ou non fiable.

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

Passez exactement l’un de --collection ou --all. La réparation distante nécessite un utilisateur Admin et un jeton d’authentification avec la portée admin.

La réparation de tout le contenu s’exécute de façon synchrone et peut être lente ou coûteuse sur de grands sites. Préférez --collection lorsque vous n’avez besoin de réparer qu’une collection.

Les résultats structurés complete, partial et stale sortent avec 0 ; les résultats structurés failed sortent avec 1. L’automatisation et les tâches cron doivent utiliser --json et analyser status, failedSourceCount, skippedSourceCount et les résumés par collection au lieu de traiter la sortie 0 comme une couverture complète.

emdash search

Recherche plein texte dans le contenu.

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

emdash taxonomy

Gère les taxonomies et les termes.

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

Gère les menus de navigation.

menu list

npx emdash menu list

menu get <name>

npx emdash menu get primary

Renvoie le menu avec tous ses éléments.

emdash site

Exporte un site entier vers un paquet de site .emdash, et importe un paquet dans un site vide. Le guide de transfert de site explique ce qu’un paquet contient, ce dont le site cible a besoin, et comment lire un plan d’import.

Le jeton a besoin de la portée admin, que le jeton de emdash login possède, ou des portées de transfert correspondantes : transfer:export pour exporter, et transfer:analyze et transfer:execute pour importer. Un jeton sans elles échoue avec INSUFFICIENT_SCOPE.

Les messages de progression vont toujours vers stderr, et le résultat vers stdout. Avec --json, ou lorsque stdout n’est pas un terminal, stdout ne contient que le résultat JSON. Une erreur est écrite comme { "error": { "code": "…", "message": "…" } }. Les codes sont les codes d’erreur du serveur, plus INVALID_ARGUMENT pour de mauvais flags, PACKAGE_FILE_REQUIRED lorsqu’un import repris a encore besoin du fichier de paquet, et UNKNOWN_ERROR.

Les commandes réessayent les échecs réseau et les réponses 408, 429 et 5xx avec backoff.

site export

Exporte le site et l’écrit dans un fichier de paquet :

npx emdash site export --output site.emdash

La commande démarre un export, l’avance jusqu’à son achèvement et télécharge le fichier de paquet fichier par fichier. Elle vérifie que le manifeste téléchargé correspond au digest du paquet de l’export, et échoue avec TRANSFER_PACKAGE_DIGEST_MISMATCH avant d’écrire quoi que ce soit s’il ne correspond pas. Elle vérifie la taille et le digest SHA-256 de chaque fichier avant de l’écrire. Le paquet est écrit dans <output>.partial et renommé vers le chemin de sortie lorsqu’il est complet.

La commande conserve sa progression dans <output>.partial.json et les fichiers téléchargés dans le répertoire <output>.parts/. Relancez la même commande après une interruption pour reprendre le même export ; les fichiers déjà téléchargés sont vérifiés et réutilisés, et la commande indique combien elle a réutilisés. Les deux sont supprimés lorsque le paquet est écrit. Le fichier de progression est ignoré lorsqu’il a été écrit pour une autre URL ou un autre réglage de commentaires, ou lorsque son export a échoué ou a expiré ; la commande démarre alors un nouvel export.

Le résultat JSON contient operationId, output, packageDigest, files, bytes et resumed.

site import <file>

Importe un paquet en deux étapes. Analysez-le d’abord, puis confirmez le digest du plan que l’analyse a imprimé :

npx emdash site import site.emdash --analyze
npx emdash site import site.emdash --plan sha256:3f1c… --confirm

--analyze vérifie tout le fichier de paquet localement, puis trouve l’import existant du même paquet sur le site ou en crée un. Il téléverse les fichiers que le site n’a pas encore, exécute l’analyse et imprime le plan : les digests du paquet et du plan, les comptes d’enregistrements, les tailles, le choix du titre et du slogan, chaque principal et son mappage, les transformations sous « Differences from the source site », les avertissements et les bloqueurs. Si un import antérieur du même paquet a échoué, a été annulé ou abandonné, ou a expiré, la commande avertit et démarre un nouvel import.

Les décisions sont stockées avec l’import, de sorte qu’une exécution ultérieure de --analyze sans flags de décision les conserve. Chaque changement de décisions produit un nouveau digest de plan. Les décisions ne peuvent pas être combinées avec --plan, et --plan ne peut pas être combiné avec --analyze.

--plan <digest> --confirm exécute l’import uniquement lorsque le digest correspond au plan actuel, puis l’avance jusqu’à son achèvement et imprime le reçu. Si le plan a changé depuis votre examen, la commande échoue avec TRANSFER_PLAN_DIGEST_MISMATCH ; analysez à nouveau et confirmez le nouveau digest.

Le résultat JSON de --analyze contient operationId, state, packageDigest, planDigest, executable et le plan complet. Le résultat JSON de --confirm contient operationId, state (complete), receipt et receiptDigestValid, qui indique si le receiptDigest du reçu correspond à son contenu.

Ces formes opèrent sur un import par son ID d’opération :

cancel et abandon demandent confirmation. Passez --yes pour ignorer l’invite ; l’invite est aussi ignorée avec --json ou lorsque stdout n’est pas un terminal. Lorsque stdin n’est pas un terminal et qu’aucun des deux ne s’applique, la commande échoue avec INVALID_ARGUMENT. Refuser l’invite ne change rien et sort avec le code 1. Le résultat JSON des deux est { operationId, state, operation }.

Les commandes d’import sortent avec ces codes :

emdash plugin

Crée, valide, empaquette et publie des plugins EmDash. La connexion au marketplace est distincte de la connexion à une instance CMS.

plugin init

Échafaude un plugin sandboxed ou natif :

npx emdash plugin init --dir ./my-plugin --name my-plugin --format sandboxed

plugin bundle

Valide un plugin et crée son tarball marketplace :

npx emdash plugin bundle --dir ./my-plugin --outDir ./artifacts

plugin validate

Exécute la même validation que plugin bundle sans créer de tarball :

npx emdash plugin validate --dir ./my-plugin

Le --dir optionnel sélectionne le répertoire du plugin et vaut par défaut le répertoire courant.

plugin publish

Téléverse un bundle vers le marketplace et, par défaut, attend son résultat de traitement :

npx emdash plugin publish --tarball ./dist/my-plugin-1.0.0.tar.gz

Fournissez --tarball, ou passez --build pour construire depuis --dir d’abord.

plugin login

S’authentifie auprès du marketplace via GitHub device flow. --registry sélectionne un autre marketplace et vaut par défaut https://marketplace.emdashcms.com.

npx emdash plugin login

plugin logout

Supprime l’identifiant marketplace enregistré. Le --registry optionnel doit identifier le même marketplace que pour la connexion.

npx emdash plugin logout

emdash export-seed

Exporte le schéma de la base et le contenu sous forme de fichier seed. Fonctionne directement sur un fichier SQLite local.

La base doit avoir chaque migration connue de la version EmDash installée. Si la commande signale des migrations en attente, exécutez npx emdash migrate, puis exportez à nouveau. Si la base a été migrée par une version EmDash plus récente, mettez à jour la version installée avant d’exporter. L’export ouvre la base en lecture seule et n’applique jamais de migrations lui-même.

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

Options

Format de sortie

Le fichier seed exporté inclut :

• Settings : Titre du site, slogan, liens sociaux
• Collections : Toutes les définitions de collection avec champs
• Block types : Chaque version conservée et le pointeur de version active de chaque type
• Taxonomies : Définitions de taxonomie et termes
• Menus : Menus de navigation avec éléments
• Redirects : Règles de redirection avec statut 301, 302, 307 ou 308
• Widget Areas : Zones de widgets et widgets
• Sections : Blocs de contenu réutilisables
• Content (si demandé) : Entrées avec références $media et syntaxe $ref: pour la portabilité

Les entrées planifiées sont exportées comme brouillons, car un seed n’a pas de champ pour une heure de publication. L’export omet, avec un avertissement sur stderr, tout ce que emdash seed rejetterait : règles de redirection avec statut 410 ou 451, règles supplémentaires partageant une source (possible dans d’anciennes bases), et sections dont le slug contient des caractères autres que des lettres minuscules, des chiffres et des tirets.

URLs de médias

emdash seed télécharge chaque URL $media et téléverse le fichier vers le stockage du site cible, il a donc besoin d’une URL http ou https absolue qu’il peut atteindre. Passez l’URL publique du site source pour écrire des URLs absolues :

npx emdash export-seed --with-content=all --media-base-url=https://example.com > seed.json

Le site doit servir ses médias depuis /_emdash/api/media/file/ sous cette URL pendant l’application du seed, et l’URL ne doit pas pointer vers localhost ni une adresse de réseau privé, depuis lesquels emdash seed refuse de télécharger. Sans --media-base-url, les URLs $media sont des chemins relatifs au site que emdash seed ignore, laissant les champs vides, et l’export imprime un avertissement sur stderr.

Les champs image et fichier, et les sous-champs image des repeaters, sont exportés comme références $media. Les images dans les champs Portable Text conservent leur ID média et URL stockés, qui ne se résolvent pas sur un autre site.

emdash secrets

Génère et inspecte la clé utilisée pour chiffrer les secrets de plugins.

secrets generate

Génère un EMDASH_ENCRYPTION_KEY pour votre déploiement. La clé est utilisée pour chiffrer les secrets de plugins au repos.

npx emdash secrets generate

Imprime la nouvelle clé sur stdout. Dirigez-la par pipe vers votre magasin de secrets, ou écrivez-la directement dans votre fichier .env local avec --write. Wrangler et le plugin Vite Cloudflare lisent ce fichier en développement local. Un serveur Node autonome ne charge pas .env automatiquement ; chargez-le via le gestionnaire de processus ou fournissez la clé via l’environnement de processus du serveur. Le guide de déploiement Node.js montre la commande locale.

npx emdash secrets generate --write .env

--write refuse d’écraser une entrée existante sans --force. Pour faire tourner un déploiement avec des données chiffrées existantes, placez la clé générée devant la valeur existante et séparez les clés par une virgule. EmDash chiffre les nouvelles valeurs avec la première clé et utilise les entrées plus anciennes pour le déchiffrement par kid. Réenregistrez chaque secret de plugin avant de supprimer une ancienne clé. EmDash ne liste actuellement pas les ID de clés encore utilisés par les réglages stockés, donc conservez un inventaire des identifiants que vous réenregistrez et vérifiez chaque intégration avant de supprimer son ancienne clé.

secrets fingerprint <key>

Imprime l’empreinte de 8 caractères (kid) d’une clé sans exposer sa valeur. Utile en CI pour vérifier que la bonne clé a été déployée. La commande suivante imprime l’empreinte d’une clé :

npx emdash secrets fingerprint emdash_enc_v1_...

emdash auth (obsolète)

auth secret

Génère une valeur legacy EMDASH_AUTH_SECRET :

npx emdash auth secret

Les installations existantes peuvent conserver cette variable pour préserver des hachages IP de commentateurs stables. Elle ne chiffre pas les secrets de plugins.

Fichiers générés

emdash-env.d.ts

L’intégration Astro génère emdash-env.d.ts à la racine du projet lorsque le serveur de développement local démarre. Elle actualise le fichier après des changements de schéma effectués via le site de développement en cours d’exécution. Les déclarations augmentent EmDashCollections, de sorte que des appels tels que getEmDashCollection("posts") déduisent les champs définis dans la base locale.

Ce fichier est automatique et appartient au flux de développement Astro local. Vous n’avez pas besoin d’exécuter emdash types pour le créer.

.emdash/types.ts

La commande emdash types récupère le schéma d’une instance en cours d’exécution et écrit des interfaces TypeScript autonomes. Utilisez-la lorsque le schéma se trouve sur une instance EmDash distante, lorsque des outils ont besoin d’un fichier à un chemin personnalisé, ou lorsque le serveur de développement Astro local n’est pas en cours d’exécution :

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

import type { PortableTextBlock } from "emdash";

export interface Post {
	id: string;
	slug: string | null;
	status: string;
	title: string;
	content?: PortableTextBlock[];
	createdAt: Date;
	updatedAt: Date;
	publishedAt: Date | null;
	bylines?: ContentBylineCredit[];
	terms?: Record<string, TaxonomyTerm[]>;
}

La sortie distante contient des interfaces de collection autonomes et n’augmente pas EmDashCollections. Elle ne change que lorsque vous exécutez emdash types ; emdash-env.d.ts utilise l’augmentation de modules et s’actualise dans le cadre du développement local.

.emdash/schema.json

La commande écrit aussi une exportation de schéma brute nommée schema.json à côté de la sortie TypeScript sélectionnée. Avec le chemin de sortie par défaut, le fichier est .emdash/schema.json :

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

Variables d’environnement

Scripts de paquet

Ajoutez des commandes courantes comme scripts package.json pour plus de commodité :

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

Codes de sortie généraux

La plupart des commandes utilisent 0 pour le succès et 1 pour une erreur. emdash migrate utilise aussi les codes 2, 3, 4 et 130 pour les résultats spécifiques listés dans son tableau de codes de sortie. emdash site import utilise 2 lorsque le plan d’import a des bloqueurs.