Référence CLI

La CLI 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

La CLI est incluse avec le package 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 em pour plus de brièveté.

Authentification

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

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

La plupart des commandes acceptent les flags --url (par défaut http://localhost:4321) et --token. Lors du ciblage d’un serveur de développement local, aucun token n’est nécessaire.

Flags communs

Ces flags sont disponibles sur toutes les commandes distantes :

Sortie

Lorsque stdout est un TTY, la CLI affiche les résultats formatés avec consola. Lorsqu’elle est pipée ou lorsque --json est défini, elle génère du JSON brut vers 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 développement
npx emdash dev

# Port personnalisé
npx emdash dev --port 3000

# Générer les types depuis un serveur 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 les types TypeScript à partir d’une instance distante (URL depuis env EMDASH_URL ou emdash.url dans package.json)
3. Démarre le serveur de développement Astro avec EMDASH_DATABASE_URL défini

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

# Générer les types depuis le serveur de développement 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 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 points de terminaison d’authentification depuis l’instance
2. Si localhost et aucune authentification configurée, utilise automatiquement le contournement dev
3. Sinon, lance OAuth Device Flow — affiche un code et ouvre votre navigateur
4. Interroge pour l’autorisation, puis sauvegarde les identifiants dans ~/.config/emdash/auth.json

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

emdash logout

Déconnectez-vous et supprimez les identifiants stockés.

npx emdash logout [options]

Options

emdash whoami

Affiche l’utilisateur actuellement authentifié.

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è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 token _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 une de --data, --file ou --stdin. Les nouveaux éléments sont automatiquement 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 changements que vous n’avez pas vus. 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": "Updated"}'

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

Supprime doucement l’élément de contenu (déplace vers 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 mis à la corbeille.

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

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

Retourne le menu avec tous ses éléments.

emdash export-seed

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

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

Options

Format de sortie

Le fichier seed exporté inclut :

• Paramètres : Titre du site, slogan, liens sociaux
• Collections : Toutes les définitions de collection avec les champs
• Taxonomies : Définitions de taxonomie 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 une EMDASH_ENCRYPTION_KEY pour votre déploiement. La clé est utilisée pour chiffrer les secrets des plugins au repos.

npx emdash secrets generate

Affiche la nouvelle clé vers stdout. Redirigez-la vers votre magasin de secrets, ou écrivez-la directement dans un fichier de développement avec --write. Les commandes suivantes écrivent la clé dans .dev.vars ou .env :

npx emdash secrets generate --write .dev.vars
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. Ceci est utile en CI pour vérifier que la bonne clé a été déployée. La commande suivante affiche l’empreinte digitale 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 :

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

La commande écrit également 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 CLI comme scripts package.json pour plus de commodité :

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

Codes de sortie