Referencia del CLI

El CLI de EmDash proporciona comandos para gestionar una instancia de EmDash CMS — configuración de base de datos, generación de tipos, CRUD de contenido, gestión de esquemas, medios y más.

Instalación

El CLI está incluido con el paquete emdash. Instálalo con el siguiente comando:

npm install emdash

Ejecuta comandos con npx emdash o añade scripts a package.json. El binario también está disponible como em por brevedad.

Autenticación

Los comandos que usan el cliente remoto compartido resuelven la autenticación en este orden:

1. Flag --token — token explícito en la línea de comandos
2. Variable de entorno EMDASH_TOKEN
3. Credenciales almacenadas de ~/.config/emdash/auth.json (guardadas por emdash login)
4. Bypass de desarrollo — si la URL es localhost y no hay token disponible, se autentica automáticamente vía el endpoint de bypass de desarrollo

Estos comandos aceptan flags --url (de EMDASH_URL, con fallback a http://localhost:4321) y --token. Los comandos de autenticación tienen sus propias opciones de conexión. Al apuntar a un servidor de desarrollo local, no se necesita token.

Flags comunes

Estos flags están disponibles en comandos que usan el cliente remoto compartido:

Salida

Cuando stdout es un TTY, el CLI imprime resultados formateados con consola. Cuando se hace pipe o cuando --json está establecido, produce JSON crudo a stdout — adecuado para jq u otras herramientas.

Comandos

emdash dev

Inicia el servidor de desarrollo con configuración automática de base de datos.

npx emdash dev [options]

Opciones

Ejemplos

# Iniciar servidor de desarrollo
npx emdash dev

# Puerto personalizado
npx emdash dev --port 3000

# Generar tipos desde remoto antes de iniciar
npx emdash dev --types

Comportamiento

1. Verifica y ejecuta migraciones de base de datos pendientes
2. Si --types está establecido, genera tipos TypeScript desde una instancia remota (URL de la variable EMDASH_URL o emdash.url en package.json)
3. Inicia el servidor de desarrollo Astro con EMDASH_DATABASE_URL establecido

emdash types

Genera tipos TypeScript desde el esquema de una instancia EmDash en ejecución.

npx emdash types [options]

Opciones

Ejemplos

# Generar tipos desde servidor local
npx emdash types

# Generar desde instancia remota
npx emdash types --url https://my-site.pages.dev

# Ruta de salida personalizada
npx emdash types --output src/types/emdash.ts

Comportamiento

1. Obtiene el esquema de la instancia
2. Genera definiciones de tipos TypeScript
3. Escribe los tipos en el archivo de salida
4. Escribe un schema.json junto para referencia

emdash login

Inicia sesión en una instancia EmDash usando OAuth Device Flow.

npx emdash login [options]

Opciones

Comportamiento

1. Descubre endpoints de autenticación de la instancia
2. Si es localhost y no hay auth configurada, usa bypass de desarrollo automáticamente
3. De lo contrario inicia OAuth Device Flow — muestra un código y abre tu navegador
4. Sondea la autorización, luego guarda credenciales en ~/.config/emdash/auth.json

Las credenciales guardadas se usan automáticamente por todos los comandos posteriores dirigidos a la misma instancia.

emdash logout

Cerrar sesión y eliminar credenciales almacenadas.

npx emdash logout [options]

Opciones

emdash whoami

Muestra el usuario autenticado actual.

npx emdash whoami [options]

Opciones

Muestra email, nombre, rol, método de autenticación y URL de la instancia.

emdash content

Gestionar elementos de contenido. Todos los subcomandos usan la API remota vía 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 respuesta incluye un token _rev. Pásalo a content update para confirmar que has visto el estado actual antes de sobrescribir.

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

Proporciona datos mediante exactamente una de --data, --file o --stdin. Los nuevos elementos se auto-publican a menos que --draft esté establecido.

content update <collection> <id>

Debes proporcionar el token _rev de un get previo para probar que has visto el estado actual. Esto evita sobrescribir cambios que no has visto. Los siguientes pasos leen un elemento y luego lo actualizan con ese token:

# 1. Leer el elemento, anotar el _rev
npx emdash content get posts 01ABC123

# 2. Actualizar con el _rev del paso 1
npx emdash content update posts 01ABC123 \
  --rev MToyMDI2LTAyLTE0... \
  --data '{"title": "Actualizado"}'

Si el elemento ha cambiado desde tu get, el servidor devuelve 409 Conflict — vuelve a leer e intenta de nuevo.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Eliminación suave del elemento de contenido (mueve a la papelera).

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

Restaura un elemento de contenido eliminado.

emdash schema

Gestionar colecciones y campos.

schema list

npx emdash schema list

Lista todas las colecciones.

schema get <collection>

npx emdash schema get posts

Muestra una colección con todos sus campos.

schema create <collection>

npx emdash schema create articles --label Articles
npx emdash schema create articles --label Articles --label-singular Article --description "Artículos del blog"

schema delete <collection>

npx emdash schema delete articles
npx emdash schema delete articles --force

Solicita confirmación a menos que --force esté establecido.

schema add-field <collection> <field>

npx emdash schema add-field posts body --type portableText --label "Contenido del cuerpo"
npx emdash schema add-field posts featured --type boolean --required

schema remove-field <collection> <field>

npx emdash schema remove-field posts featured

emdash media

Gestionar elementos de medios.

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 atardecer" --caption "Tomada en Bristol"

media get <id>

npx emdash media get 01MEDIA123

media delete <id>

npx emdash media delete 01MEDIA123

media repair-usage

Reparar índices de uso de medios de contenido para una colección o para todas las colecciones de contenido. Usa esto después de importaciones o escrituras directas a la base de datos cuando la cobertura de uso es obsoleta o no confiable.

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

Pasa exactamente una de --collection o --all. La reparación remota requiere un usuario Admin y un token de autenticación con el scope admin.

La reparación de todo el contenido se ejecuta sincrónicamente y puede ser lenta o costosa en sitios grandes. Prefiere --collection cuando solo necesitas reparar una colección.

Los resultados de reparación estructurados complete, partial y stale salen con 0; los resultados failed estructurados salen con 1. La automatización y los trabajos cron deberían usar --json y parsear status, failedSourceCount, skippedSourceCount y resúmenes por colección en lugar de tratar exit 0 como cobertura completa.

emdash search

Búsqueda de texto completo a través del contenido.

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

emdash taxonomy

Gestionar taxonomías y términos.

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

Gestionar menús de navegación.

menu list

npx emdash menu list

menu get <name>

npx emdash menu get primary

Devuelve el menú con todos sus elementos.

emdash export-seed

Exportar esquema de base de datos y contenido como archivo semilla. Trabaja directamente con un archivo SQLite local.

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

Opciones

Formato de salida

El archivo semilla exportado incluye:

• Configuración: Título del sitio, eslogan, enlaces sociales
• Colecciones: Todas las definiciones de colecciones con campos
• Taxonomías: Definiciones de taxonomías y términos
• Menús: Menús de navegación con elementos
• Áreas de widgets: Áreas de widgets y widgets
• Contenido (si se solicita): Entradas con referencias $media y sintaxis $ref: para portabilidad

emdash secrets generate

Genera un EMDASH_ENCRYPTION_KEY para tu despliegue. La clave se usa para cifrar secretos de plugins en reposo.

npx emdash secrets generate

Imprime la nueva clave en stdout. Dirígela a tu almacén de secretos, o escríbela directamente en tu archivo .env local con --write. El mismo archivo .env es leído por Node y, en desarrollo local, por Wrangler y el plugin Vite de Cloudflare:

npx emdash secrets generate --write .env

--write se niega a sobrescribir una entrada existente sin --force. Reemplazar una clave en un despliegue con datos cifrados existentes dejará esos secretos ilegibles, por lo que la protección es intencional.

emdash secrets fingerprint <key>

Imprime la huella digital de 8 caracteres (kid) de una clave sin exponer su valor. Esto es útil en CI para verificar que se desplegó la clave correcta. El siguiente comando imprime la huella digital de una clave:

npx emdash secrets fingerprint emdash_enc_v1_...

Archivos generados

.emdash/types.ts

El comando emdash types genera interfaces TypeScript para cada colección:

// Generado por el CLI de EmDash
// No editar manualmente - ejecuta `emdash types` para regenerar

import type { PortableTextBlock } from "emdash";

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

.emdash/schema.json

El comando también escribe una exportación de esquema crudo para herramientas:

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

Variables de entorno

Scripts de paquete

Añade los comandos del CLI como scripts de package.json por conveniencia:

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

Códigos de salida