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, ainsi que l’export et l’import de sites.

Installation

La CLI est incluse dans 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 également disponible sous le nom em, par souci de concision.

Démarrez votre site avec son script de paquet, comme 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, tant que la configuration n’est pas terminée, applique une seule fois le schéma et la structure du seed fourni. Le contenu d’exemple du seed n’est appliqué que lorsqu’un administrateur le choisit dans l’assistant de configuration.

Authentification

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

1. Option --token — jeton explicite sur la ligne de commande
2. Variable d’environnement EMDASH_TOKEN
3. Identifiants enregistrés dans ~/.config/emdash/auth.json (enregistrés par emdash login)
4. Contournement en développement — si l’URL est localhost et qu’aucun jeton n’est disponible, la commande s’authentifie automatiquement via le point de terminaison de contournement en développement

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. Lorsque vous ciblez un serveur de développement local, aucun jeton n’est nécessaire.

Options communes

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

Sortie

Lorsqu’une commande écrit ses résultats dans un terminal interactif, elle les met en forme pour la lecture. Les commandes listées ci-dessus avec --json écrivent du JSON brut lorsque l’option est définie ou que leur sortie est redirigée. emdash migrate n’émet du JSON qu’avec son option explicite --json.

Commandes

emdash init

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

npx emdash init [options]

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

emdash doctor

Vérifie une base de données SQLite locale à la recherche de problèmes de connexion, de migration, de collections, de tables et d’utilisateurs. Si le projet possède une configuration Wrangler, la commande vérifie également qu’un Cron Trigger et un gestionnaire scheduled() d’EmDash sont configurés ensemble.

npx emdash doctor [options]

La commande signale chaque vérification comme réussie, 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 de données SQLite locale. La commande utilise le chemin positionnel lorsqu’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 du cœur. Utilisez --validate en intégration continue lorsque vous devez vérifier le fichier sans ouvrir ni créer la base de données.

emdash migrate

Vérifie ou applique l’ensemble des migrations du cœur émis par un 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étecte la racine du projet et lit .emdash/migrations.json. Elle valide le manifeste par rapport au paquet EmDash installé dans le projet, résout l’exécuteur local au projet de l’adaptateur et affiche la cible immuable avant tout SQL.

Options

L’application et la libération du verrou en mode interactif, lisible par un humain, demandent une confirmation. L’application ou la libération du verrou en mode non interactif, ainsi que toute application ou libération avec --json, exigent l’empreinte exacte affichée pour la cible. Il n’existe ni down ni --dry-run ; utilisez --check pour déterminer si du travail est nécessaire.

Codes de sortie

Consultez Gérer les migrations de la base de données du cœur pour l’ordre de déploiement, les identifiants de la cible et le verrou de migration D1.

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://example.com

# 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 à l’aide du flux d’appareil OAuth (OAuth Device Flow).

npx emdash login [options]

Options

Comportement

1. Découvre les points de terminaison d’authentification de l’instance
2. Si l’URL est localhost et qu’aucune authentification n’est configurée, utilise automatiquement le contournement en développement
3. Sinon, lance le flux d’appareil OAuth : affiche un code et ouvre votre navigateur. Une fois le code saisi, la page d’administration liste les autorisations que la CLI recevra, ainsi que les autorisations demandées 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 qui ciblent la même instance.

emdash logout

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

npx emdash logout [options]

Options

emdash whoami

Affiche l’utilisateur actuellement authentifié.

npx emdash whoami [options]

Options

Affiche l’adresse 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. Toutes 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. Transmettez-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 avec exactement une des options --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 évite 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-le et réessayez.

Si quelqu’un a ouvert l’entrée dans l’administration, le serveur renvoie 409 avec le code ENTRY_LOCKED et un message qui nomme le détenteur du verrou. Attendez qu’il ait terminé, ou transmettez --override-lock. La même option est disponible sur content delete, content publish, content unpublish et content schedule.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Supprime l’élément de contenu de façon logique (le déplace dans la corbeille).

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

content publish <collection> <id>

npx emdash content publish posts 01ABC123

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

content unpublish <collection> <id>

npx emdash content unpublish posts 01ABC123

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

Transmettez --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 placé dans la corbeille.

content translations <collection> <id>

Liste toutes les traductions du groupe de traduction de l’entrée :

npx emdash content translations posts 01ABC123

Le résultat inclut l’identifiant, la locale, le slug et le statut de chaque traduction, ainsi que l’indication de savoir 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 une 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 du contenu pour une collection ou pour toutes les collections de contenu. Utilisez-le après des imports ou des écritures directes dans la base de données lorsque la couverture d’utilisation est obsolète ou jugée non fiable.

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

Transmettez exactement une des options --collection ou --all. La réparation à distance nécessite un utilisateur Admin et un jeton d’authentification ayant 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 les gros sites. Préférez --collection lorsque vous n’avez besoin de réparer qu’une seule collection.

Les résultats de réparation structurés complete, partial et stale se terminent avec 0 ; les résultats structurés failed se terminent avec 1. Les automatisations et les tâches cron doivent utiliser --json et analyser status, failedSourceCount, skippedSourceCount ainsi que les résumés par collection, au lieu de considérer le code de sortie 0 comme une couverture complète.

emdash search

Recherche en texte intégral 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 que contient un paquet, ce dont le site cible a besoin et comment lire un plan d’import.

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

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

Les commandes réessaient les échecs réseau et les réponses 408, 429 et 5xx avec un délai progressif (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, le fait avancer jusqu’à son terme et télécharge le fichier de paquet fichier par fichier. Elle vérifie que le manifeste téléchargé correspond au condensé (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 condensé SHA-256 de chaque fichier avant de l’écrire. Le paquet est écrit dans <output>.partial puis renommé vers le chemin de sortie une fois complet.

La commande conserve sa progression dans <output>.partial.json et les fichiers téléchargés dans le répertoire <output>.parts/. Exécutez à nouveau 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 en a réutilisé. 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 des commentaires, ou lorsque son export a échoué ou 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 condensé du plan que l’analyse a affiché :

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

--analyze vérifie localement tout le fichier du paquet, 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, lance l’analyse et affiche le plan : les condensés du paquet et du plan, le nombre d’enregistrements, les tailles, le choix du titre et du slogan, chaque principal et son association, les transformations sous « Differences from the source site », les avertissements et les blocages. Si un import précédent 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 enregistrées avec l’import, de sorte qu’une exécution ultérieure de --analyze sans options de décision les conserve. Chaque modification des décisions produit un nouveau condensé 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 n’exécute l’import que si le condensé correspond au plan actuel, le fait ensuite avancer jusqu’à son terme et affiche le reçu. Si le plan a changé depuis que vous l’avez examiné, la commande échoue avec TRANSFER_PLAN_DIGEST_MISMATCH ; analysez à nouveau et confirmez le nouveau condensé.

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 à partir de son identifiant d’opération :

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

Les commandes d’import se terminent avec ces codes :

emdash export-seed

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

La base de données doit contenir toutes les migrations connues de la version d’EmDash installée. Si la commande signale des migrations en attente, exécutez npx emdash migrate, puis exportez à nouveau. Si la base de données a été migrée par une version d’EmDash plus récente, mettez à niveau la version installée avant d’exporter. L’export ouvre la base de données 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 de seed exporté comprend :

• Paramètres : titre du site, slogan, liens sociaux
• Collections : toutes les définitions de collections avec leurs champs
• Types de blocs : chaque version conservée et le pointeur de version active de chaque type
• Taxonomies : définitions de taxonomies et termes
• Menus : menus de navigation avec leurs éléments
• Redirections : règles de redirection avec le statut 301, 302, 307 ou 308
• Zones de widgets : zones de widgets et widgets
• Sections : blocs de contenu réutilisables
• Contenu (si demandé) : entrées avec des références $media et la syntaxe $ref: pour la portabilité

Les entrées planifiées sont exportées en brouillon, 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 : les règles de redirection avec le statut 410 ou 451, les règles supplémentaires qui partagent une même source (possible dans d’anciennes bases de données) et les sections dont le slug contient des caractères autres que des lettres minuscules, des chiffres et des tirets.

URL des médias

emdash seed télécharge chaque URL $media et téléverse le fichier dans le stockage du site cible ; il lui faut donc une URL http ou https absolue qu’il peut atteindre. Transmettez l’URL publique du site source pour écrire des URL 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 pointer ni vers localhost ni vers une adresse de réseau privé, depuis lesquels emdash seed refuse de télécharger. Sans --media-base-url, les URL $media sont des chemins relatifs au site que emdash seed ignore, laissant les champs vides, et l’export affiche un avertissement sur stderr.

Les champs image et fichier, ainsi que les sous-champs image des répéteurs (repeaters), sont exportés sous forme de références $media. Les images dans les champs Portable Text conservent leur identifiant de média et leur URL enregistré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 des plugins.

secrets generate

Génère une EMDASH_ENCRYPTION_KEY pour votre déploiement. La clé sert à chiffrer les secrets des plugins au repos.

npx emdash secrets generate

Affiche la nouvelle clé sur stdout. Redirigez-la vers votre gestionnaire de secrets, ou écrivez-la directement dans votre fichier .env local avec --write. Wrangler et le plugin Vite de 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 du 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 effectuer la rotation d’un déploiement contenant déjà des données chiffrées, placez la clé générée avant 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 déchiffrer selon leur kid. Réenregistrez chaque secret de plugin avant de supprimer une ancienne clé. EmDash ne liste pas actuellement les identifiants de clé encore utilisés par les paramètres enregistrés ; tenez donc un inventaire des identifiants que vous réenregistrez et vérifiez chaque intégration avant de supprimer son ancienne clé.

secrets fingerprint <key>

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

npx emdash secrets fingerprint emdash_enc_v1_...

Fichiers générés

emdash-env.d.ts

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

Ce fichier est automatique et relève du flux de développement local d’Astro. 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’étend pas EmDashCollections. Elle ne change que lorsque vous exécutez emdash types ; emdash-env.d.ts utilise l’augmentation de modules et est actualisé dans le cadre du développement local.

.emdash/schema.json

La commande écrit également un export de schéma brut nommé schema.json à côté de la sortie TypeScript choisie. 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 les commandes courantes comme scripts package.json par 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 des codes de sortie. emdash site import utilise 2 lorsque le plan d’import comporte des blocages.