Referencia de la CLI

La CLI de EmDash ofrece comandos para configurar la base de datos, generar tipos, crear y editar contenido, gestionar el esquema, administrar medios y exportar e importar sitios.

Instalación

La CLI se incluye con el paquete emdash. Instálala con el siguiente comando:

npm install emdash

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

Inicia tu sitio con su script de paquete, como pnpm dev. El script de paquete inicia Astro; la integración de EmDash genera emdash-env.d.ts, mientras que el entorno de ejecución aplica las migraciones pendientes en la primera solicitud y, antes de completar la configuración, aplica una sola vez el esquema y la estructura de la semilla incluida. El contenido de muestra de la semilla solo se aplica cuando un administrador lo elige en el asistente de configuración.

Autenticación

Los comandos que se conectan a una instancia de EmDash en ejecución resuelven la autenticación en este orden:

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

Los comandos types, whoami, content, schema, media, search, taxonomy, menu y site se conectan a una instancia en ejecución. Los comandos de autenticación tienen sus propias opciones de conexión. Al apuntar a un servidor de desarrollo local, no se necesita ningún token.

Indicadores comunes

Los indicadores de conexión varían según el comando. Los comandos agrupados que se indican a continuación se refieren a todos los subcomandos de ese grupo.

Salida

Cuando un comando escribe resultados en un terminal interactivo, les da formato para facilitar la lectura. Los comandos que se indican arriba con --json escriben JSON sin procesar cuando se establece el indicador o cuando su salida se canaliza. emdash migrate emite JSON solo con su opción explícita --json.

Comandos

emdash init

Inicializa una base de datos SQLite local a partir de los metadatos de la plantilla en package.json. El comando ejecuta las migraciones del núcleo y después aplica el archivo SQL opcional indicado en emdash.schema. Ejecuta emdash seed por separado para los datos de semilla JSON.

npx emdash init [options]

Sin --force, una base de datos ya inicializada se deja sin cambios. Este comando abre directamente un archivo SQLite local; usa emdash migrate para las migraciones de D1, PostgreSQL, libSQL o Hyperdrive gestionadas por el despliegue.

emdash doctor

Comprueba una base de datos SQLite local en busca de problemas de conexión, migraciones, colecciones, tablas y usuarios. Si el proyecto tiene una configuración de Wrangler, el comando también comprueba que un Cron Trigger y un controlador scheduled() de EmDash estén configurados juntos.

npx emdash doctor [options]

El comando informa de cada comprobación como correcta, advertencia o fallo, y termina con un código distinto de cero cuando una comprobación falla.

emdash seed

Valida o aplica una semilla JSON a una base de datos SQLite local. El comando usa la ruta posicional cuando se proporciona; si no, .emdash/seed.json y, por último, la ruta emdash.seed de package.json.

npx emdash seed [path] [options]

Aplicar una semilla ejecuta primero las migraciones del núcleo. Usa --validate en integración continua cuando necesites comprobar el archivo sin abrir ni crear la base de datos.

emdash migrate

Comprueba o aplica el conjunto de migraciones del núcleo que emite una compilación de Astro.

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

De forma predeterminada, el comando descubre la raíz del proyecto y lee .emdash/migrations.json. Valida el manifiesto con el paquete EmDash instalado en el proyecto, resuelve el ejecutor local del proyecto para el adaptador e imprime el destino inmutable antes de ejecutar cualquier SQL.

Opciones

Aplicar y liberar el bloqueo de forma interactiva y legible para personas piden confirmación. Aplicar o liberar el bloqueo de forma no interactiva, y toda aplicación o liberación con --json, requieren la huella exacta impresa para el destino. No existe down ni --dry-run; usa --check para determinar si hay trabajo pendiente.

Códigos de salida

Consulta Gestionar las migraciones de la base de datos del núcleo para conocer el orden de despliegue, las credenciales del destino y el bloqueo de migración de D1.

emdash types

Genera tipos de TypeScript a partir del esquema de una instancia de EmDash en ejecución.

npx emdash types [options]

Opciones

Ejemplos

# 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

Comportamiento

1. Obtiene el esquema de la instancia
2. Genera las definiciones de tipos de TypeScript
3. Escribe los tipos en el archivo de salida
4. Escribe schema.json junto a él como referencia

emdash login

Inicia sesión en una instancia de EmDash mediante el flujo de dispositivo de OAuth (OAuth Device Flow).

npx emdash login [options]

Opciones

Comportamiento

1. Descubre los endpoints de autenticación de la instancia
2. Si es localhost y no hay autenticación configurada, usa automáticamente el bypass de desarrollo
3. En caso contrario, inicia el flujo de dispositivo de OAuth: muestra un código y abre tu navegador. Después de introducir el código, la página de administración enumera los permisos que recibirá la CLI y los permisos solicitados que tu rol no permite, antes de que apruebes.
4. Consulta la autorización y después guarda las credenciales en ~/.config/emdash/auth.json

Las credenciales guardadas se usan automáticamente en todos los comandos posteriores que apunten a la misma instancia.

emdash logout

Cierra la sesión y elimina las credenciales almacenadas.

npx emdash logout [options]

Opciones

emdash whoami

Muestra el usuario autenticado actual.

npx emdash whoami [options]

Opciones

Muestra el correo electrónico, el nombre, el rol, el método de autenticación y la URL de la instancia.

emdash content

Gestiona elementos de contenido. Todos los subcomandos usan la API remota mediante 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 sobrescribirlo.

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 los datos mediante exactamente una de las opciones --data, --file o --stdin. Los elementos nuevos se publican automáticamente salvo que se establezca --draft.

content update <collection> <id>

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

# 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 el elemento ha cambiado desde tu get, el servidor devuelve 409 Conflict: vuelve a leerlo e inténtalo de nuevo.

Si alguien tiene la entrada abierta en la administración, el servidor devuelve 409 con el código ENTRY_LOCKED y un mensaje que nombra a quien tiene el bloqueo. Espera a que termine o pasa --override-lock. El mismo indicador está disponible en content delete, content publish, content unpublish y content schedule.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Elimina de forma lógica el elemento de contenido (lo mueve a la papelera).

Pasa --override-lock para eliminar una entrada que otro editor tiene abierta.

content publish <collection> <id>

npx emdash content publish posts 01ABC123

Pasa --override-lock para publicar una entrada que otro editor tiene abierta.

content unpublish <collection> <id>

npx emdash content unpublish posts 01ABC123

Pasa --override-lock para despublicar una entrada que otro editor tiene abierta.

content schedule <collection> <id>

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

Pasa --override-lock para programar una entrada que otro editor tiene abierta.

content restore <collection> <id>

npx emdash content restore posts 01ABC123

Restaura un elemento de contenido que está en la papelera.

content translations <collection> <id>

Enumera todas las traducciones del grupo de traducción de la entrada:

npx emdash content translations posts 01ABC123

El resultado incluye el ID, el locale, el slug y el estado de cada traducción, y si es la entrada solicitada.

emdash schema

Gestiona colecciones y campos.

schema list

npx emdash schema list

Enumera 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 "Blog articles"

schema delete <collection>

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

Pide confirmación salvo que se establezca --force.

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

Gestiona elementos multimedia.

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

Repara los índices de uso de medios del contenido para una colección o para todas las colecciones de contenido. Úsalo después de importaciones o escrituras directas en la base de datos cuando la cobertura de uso esté obsoleta o no sea fiable.

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

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

La reparación de todo el contenido se ejecuta de forma síncrona y puede ser lenta o costosa en sitios grandes. Prefiere --collection cuando solo necesites reparar una colección.

Los resultados estructurados complete, partial y stale terminan con 0; los resultados estructurados failed terminan con 1. Las automatizaciones y los trabajos cron deben usar --json y analizar status, failedSourceCount, skippedSourceCount y los resúmenes por colección, en lugar de tratar el código de salida 0 como cobertura completa.

emdash search

Búsqueda de texto completo en el contenido.

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

emdash taxonomy

Gestiona 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

Gestiona 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 site

Exporta un sitio completo a un paquete de sitio .emdash e importa un paquete en un sitio vacío. La guía de transferencia de sitios explica qué contiene un paquete, qué necesita el sitio de destino y cómo leer un plan de importación.

El token necesita el alcance admin, que tiene el token de emdash login, o los alcances de transferencia correspondientes: transfer:export para exportar, y transfer:analyze y transfer:execute para importar. Un token sin ellos falla con INSUFFICIENT_SCOPE.

Los mensajes de progreso siempre van a stderr y el resultado va a stdout. Con --json, o cuando stdout no es un terminal, stdout contiene solo el resultado JSON. Un error se escribe como { "error": { "code": "…", "message": "…" } }. Los códigos son los códigos de error del servidor, más INVALID_ARGUMENT para indicadores incorrectos, PACKAGE_FILE_REQUIRED cuando una importación reanudada todavía necesita el archivo del paquete y UNKNOWN_ERROR.

Los comandos reintentan los fallos de red y las respuestas 408, 429 y 5xx con espera progresiva (backoff).

site export

Exporta el sitio y lo escribe en un archivo de paquete:

npx emdash site export --output site.emdash

El comando inicia una exportación, la hace avanzar hasta que se completa y descarga el archivo de paquete fichero a fichero. Comprueba que el manifiesto descargado coincida con el resumen (digest) del paquete de la exportación y, si no coincide, falla con TRANSFER_PACKAGE_DIGEST_MISMATCH antes de escribir nada. Comprueba el tamaño y el resumen SHA-256 de cada archivo antes de escribirlo. El paquete se escribe en <output>.partial y se renombra a la ruta de salida cuando está completo.

El comando guarda su progreso en <output>.partial.json y los archivos descargados en el directorio <output>.parts/. Ejecuta el mismo comando de nuevo tras una interrupción para reanudar la misma exportación; los archivos ya descargados se comprueban y se reutilizan, y el comando indica cuántos ha reutilizado. Ambos se eliminan cuando se escribe el paquete. El archivo de progreso se ignora cuando se escribió para otra URL o para otra configuración de comentarios, o cuando su exportación falló o caducó; en ese caso el comando inicia una exportación nueva.

El resultado JSON contiene operationId, output, packageDigest, files, bytes y resumed.

site import <file>

Importa un paquete en dos pasos. Analízalo primero y después confirma el resumen (digest) del plan que imprimió el análisis:

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

--analyze verifica localmente todo el archivo del paquete y después busca la importación existente del mismo paquete en el sitio o crea una. Sube los archivos que el sitio aún no tiene, ejecuta el análisis e imprime el plan: los resúmenes del paquete y del plan, el número de registros, los tamaños, la elección de título y lema, cada principal y su asignación, las transformaciones bajo «Differences from the source site», las advertencias y los bloqueos. Si una importación anterior del mismo paquete falló, se canceló o se abandonó, o caducó, el comando avisa e inicia una importación nueva.

Las decisiones se almacenan con la importación, de modo que una ejecución posterior de --analyze sin indicadores de decisión las conserva. Cada cambio de decisiones produce un resumen de plan nuevo. Las decisiones no se pueden combinar con --plan, y --plan no se puede combinar con --analyze.

--plan <digest> --confirm ejecuta la importación solo cuando el resumen coincide con el plan actual, la hace avanzar hasta que se completa e imprime el recibo. Si el plan cambió desde que lo revisaste, el comando falla con TRANSFER_PLAN_DIGEST_MISMATCH; analiza de nuevo y confirma el resumen nuevo.

El resultado JSON de --analyze contiene operationId, state, packageDigest, planDigest, executable y el plan completo. El resultado JSON de --confirm contiene operationId, state (complete), receipt y receiptDigestValid, que indica si el receiptDigest del recibo coincide con su contenido.

Estas formas operan sobre una importación por su ID de operación:

cancel y abandon piden confirmación. Pasa --yes para omitir la solicitud; esta también se omite con --json o cuando stdout no es un terminal. Cuando stdin no es un terminal y no se da ninguno de esos casos, el comando falla con INVALID_ARGUMENT. Rechazar la solicitud no cambia nada y termina con el código 1. El resultado JSON de ambos es { operationId, state, operation }.

Los comandos de importación terminan con estos códigos:

emdash export-seed

Exporta el esquema de la base de datos y el contenido como un archivo de semilla. Funciona directamente sobre un archivo SQLite local.

La base de datos debe tener todas las migraciones que conoce la versión de EmDash instalada. Si el comando informa de migraciones pendientes, ejecuta npx emdash migrate y vuelve a exportar. Si la base de datos fue migrada por una versión más reciente de EmDash, actualiza la versión instalada antes de exportar. La exportación abre la base de datos en modo de solo lectura y nunca aplica migraciones por sí misma.

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

Opciones

Formato de salida

El archivo de semilla exportado incluye:

• Ajustes: título del sitio, lema, enlaces sociales
• Colecciones: todas las definiciones de colecciones con sus campos
• Tipos de bloque: cada versión conservada y el puntero a la versión activa de cada tipo
• Taxonomías: definiciones de taxonomías y términos
• Menús: menús de navegación con sus elementos
• Redirecciones: reglas de redirección con estado 301, 302, 307 o 308
• Áreas de widgets: áreas de widgets y widgets
• Secciones: bloques de contenido reutilizables
• Contenido (si se solicita): entradas con referencias $media y la sintaxis $ref: para la portabilidad

Las entradas programadas se exportan como borradores, porque una semilla no tiene un campo para la hora de publicación. La exportación omite, con una advertencia en stderr, todo lo que emdash seed rechazaría: reglas de redirección con estado 410 o 451, reglas adicionales que comparten un origen (posible en bases de datos antiguas) y secciones cuyo slug contiene caracteres distintos de letras minúsculas, dígitos y guiones.

URL de medios

emdash seed descarga cada URL $media y sube el archivo al almacenamiento del sitio de destino, por lo que necesita una URL http o https absoluta a la que pueda acceder. Pasa la URL pública del sitio de origen para escribir URL absolutas:

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

El sitio debe servir sus medios desde /_emdash/api/media/file/ bajo esa URL mientras se aplica la semilla, y la URL no debe apuntar a localhost ni a una dirección de red privada, desde las cuales emdash seed se niega a descargar. Sin --media-base-url, las URL $media son rutas relativas al sitio que emdash seed omite, dejando los campos vacíos, y la exportación imprime una advertencia en stderr.

Los campos de imagen y de archivo, y los subcampos de imagen de los repetidores (repeaters), se exportan como referencias $media. Las imágenes dentro de los campos Portable Text conservan su ID de medio y su URL almacenados, que no se resuelven en otro sitio.

emdash secrets

Genera e inspecciona la clave usada para cifrar los secretos de los plugins.

secrets generate

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

npx emdash secrets generate

Imprime la nueva clave en stdout. Canalízala a tu almacén de secretos o escríbela directamente en tu archivo .env local con --write. Wrangler y el plugin de Vite de Cloudflare leen ese archivo en el desarrollo local. Un servidor Node independiente no carga .env automáticamente; cárgalo mediante el gestor de procesos o proporciona la clave a través del entorno del proceso del servidor. La guía de despliegue en Node.js muestra el comando local.

npx emdash secrets generate --write .env

--write se niega a sobrescribir una entrada existente sin --force. Para rotar un despliegue con datos cifrados existentes, antepón la clave generada al valor existente y separa las claves con una coma. EmDash cifra los valores nuevos con la primera clave y usa las entradas más antiguas para descifrar según su kid. Vuelve a guardar cada secreto de plugin antes de eliminar una clave antigua. EmDash no enumera actualmente los ID de clave que siguen usando los ajustes almacenados, así que mantén un inventario de las credenciales que vuelvas a guardar y verifica cada integración antes de eliminar su clave antigua.

secrets fingerprint <key>

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

npx emdash secrets fingerprint emdash_enc_v1_...

Archivos generados

emdash-env.d.ts

La integración de Astro genera emdash-env.d.ts en la raíz del proyecto cuando se inicia el servidor de desarrollo local. Actualiza el archivo después de los cambios de esquema realizados a través del sitio de desarrollo en ejecución. Las declaraciones amplían EmDashCollections, de modo que llamadas como getEmDashCollection("posts") infieren los campos definidos en la base de datos local.

Este archivo es automático y pertenece al flujo de desarrollo local de Astro. No necesitas ejecutar emdash types para crearlo.

.emdash/types.ts

El comando emdash types obtiene el esquema de una instancia en ejecución y escribe interfaces de TypeScript independientes. Úsalo cuando el esquema vive en una instancia remota de EmDash, cuando las herramientas necesitan un archivo en una ruta personalizada o cuando el servidor de desarrollo local de Astro no está en ejecución:

// 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 salida remota contiene interfaces de colección independientes y no amplía EmDashCollections. Solo cambia cuando ejecutas emdash types; emdash-env.d.ts usa aumento de módulos y se actualiza como parte del desarrollo local.

.emdash/schema.json

El comando también escribe una exportación de esquema sin procesar llamada schema.json junto a la salida de TypeScript seleccionada. Con la ruta de salida predeterminada, el archivo es .emdash/schema.json:

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

Variables de entorno

Scripts de paquete

Añade los comandos habituales como scripts de package.json para mayor comodidad:

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

Códigos de salida generales

La mayoría de los comandos usan 0 para el éxito y 1 para un error. emdash migrate también usa los códigos 2, 3, 4 y 130 para los resultados específicos indicados en su tabla de códigos de salida. emdash site import usa 2 cuando el plan de importación tiene bloqueos.