Référence du CLI

Le CLI d’EmDash fournit des commandes pour gérer une instance EmDash CMS — configuration de base de données, génération de types, CRUD de contenu, gestion de schéma, médias et plus encore.

Installation

Le CLI est inclus avec le package emdash. Installez-le 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 le nom em pour plus de concision.

Authentification

Les commandes utilisant le client distant partagé résolvent l’authentification dans cet ordre :

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

Ces commandes acceptent les flags --url (depuis EMDASH_URL, avec fallback sur http://localhost:4321) et --token. Les commandes d’authentification ont leurs propres options de connexion. En ciblant un serveur de dev local, aucun token n’est nécessaire.

Flags communs

Ces flags sont disponibles sur les commandes utilisant le client distant partagé :

Sortie

Quand stdout est un TTY, le CLI affiche les résultats formatés avec consola. Quand pipé ou quand --json est défini, il produit du JSON brut sur stdout — adapté pour jq ou d’autres outils.

Commandes

emdash dev

Démarre le serveur de développement avec configuration automatique de la base de données.

npx emdash dev [options]

Options

Exemples

# Démarrer le serveur de dev
npx emdash dev

# Port personnalisé
npx emdash dev --port 3000

# Générer les types depuis le distant avant de démarrer
npx emdash dev --types

Comportement

1. Vérifie et exécute les migrations de base de données en attente
2. Si --types est défini, génère des types TypeScript depuis une instance distante (URL depuis la variable EMDASH_URL ou emdash.url dans package.json)
3. Démarre le serveur de dev Astro avec EMDASH_DATABASE_URL défini

emdash types

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

npx emdash types [options]

Options

Exemples

# Générer les types depuis le serveur de dev local
npx emdash types

# Générer depuis une instance distante
npx emdash types --url https://my-site.pages.dev

# Chemin de sortie personnalisé
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 un schema.json à côté pour référence

emdash login

Connectez-vous à une instance EmDash en utilisant OAuth Device Flow.

npx emdash login [options]

Options

Comportement

1. Découvre les endpoints d’authentification de l’instance
2. Si localhost et aucune auth configurée, utilise automatiquement le bypass de dev
3. Sinon initie OAuth Device Flow — affiche un code et ouvre votre navigateur
4. Sonde l’autorisation, puis sauvegarde les identifiants dans ~/.config/emdash/auth.json

Les identifiants sauvés sont utilisés automatiquement par toutes les commandes ultérieures ciblant la même instance.

emdash logout

Déconnexion et suppression des identifiants stockés.

npx emdash logout [options]

Options

emdash whoami

Affiche l’utilisateur authentifié actuel.

npx emdash whoami [options]

Options

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

emdash content

Gérer 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 token _rev. Passez-le à content update pour confirmer que vous avez vu l’état actuel avant d’é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 une des options --data, --file ou --stdin. Les nouveaux éléments sont auto-publiés sauf si --draft est défini.

content update <collection> <id>

Vous devez fournir le token _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 token :

# 1. Lire l'élément, noter le _rev
npx emdash content get posts 01ABC123

# 2. Mettre à jour avec le _rev de l'étape 1
npx emdash content update posts 01ABC123 \
  --rev MToyMDI2LTAyLTE0... \
  --data '{"title": "Mis à jour"}'

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

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Suppression douce de l’élément de contenu (déplacé à la corbeille).

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

Restaure un élément de contenu supprimé.

emdash schema

Gérer 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 "Articles de blog"

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 "Contenu du corps"
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érer les éléments média.

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 "Un coucher de soleil" --caption "Prise à Bristol"

media get <id>

npx emdash media get 01MEDIA123

media delete <id>

npx emdash media delete 01MEDIA123

media repair-usage

Réparer les index d’utilisation des médias de contenu pour une collection ou pour toutes les collections de contenu. Utilisez ceci après des importations ou des écritures directes en base de données quand 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 une des options --collection ou --all. La réparation distante nécessite un utilisateur Admin et un token d’auth avec le scope admin.

La réparation de tout le contenu s’exécute de manière synchrone et peut être lente ou coûteuse sur les grands sites. Préférez --collection quand vous n’avez besoin de réparer qu’une seule collection.

Les résultats de réparation structurés complete, partial et stale sortent avec 0 ; les résultats failed structurés sortent avec 1. L’automatisation et les tâches cron devraient utiliser --json et parser 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 à travers le contenu.

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

emdash taxonomy

Gérer 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érer les menus de navigation.

menu list

npx emdash menu list

menu get <name>

npx emdash menu get primary

Retourne le menu avec tous ses éléments.

emdash export-seed

Exporter le schéma de base de données et le contenu comme fichier de semence. Fonctionne directement sur un fichier SQLite local.

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

Options

Format de sortie

Le fichier de semence exporté inclut :

• Paramètres : Titre du site, accroche, liens sociaux
• Collections : Toutes les définitions de collections avec champs
• Taxonomies : Définitions de taxonomies et termes
• Menus : Menus de navigation avec éléments
• Zones de widgets : Zones de widgets et widgets
• Contenu (si demandé) : Entrées avec références $media et syntaxe $ref: pour la portabilité

emdash 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

Affiche la nouvelle clé sur stdout. Redirigez-la vers votre magasin de secrets, ou écrivez-la directement dans votre fichier .env local avec --write. Le même fichier .env est lu par Node et, en développement local, par Wrangler et le plugin Vite de Cloudflare :

npx emdash secrets generate --write .env

--write refuse d’écraser une entrée existante sans --force. Remplacer une clé dans un déploiement avec des données chiffrées existantes rendra ces secrets illisibles, donc la protection est intentionnelle.

emdash secrets fingerprint <key>

Affiche l’empreinte digitale 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 affiche l’empreinte d’une clé :

npx emdash secrets fingerprint emdash_enc_v1_...

Fichiers générés

.emdash/types.ts

La commande emdash types génère des interfaces TypeScript pour chaque collection :

// Généré par le CLI EmDash
// Ne pas éditer manuellement - exécutez `emdash types` pour régénérer

import type { PortableTextBlock } from "emdash";

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

.emdash/schema.json

La commande écrit aussi une exportation de schéma brut pour l’outillage :

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

Variables d’environnement

Scripts de package

Ajoutez les commandes du CLI comme scripts package.json par commodité :

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

Codes de sortie