Referencia de la CLI

La CLI de EmDash proporciona comandos para la configuración de la base de datos, generación de tipos, creación y edición de contenido, gestión del esquema, medios, exportación e importación del sitio y desarrollo de plugins.

Instalación

La CLI se incluye con el paquete emdash. Instálala 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.

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 runtime ejecuta las migraciones pendientes en la primera solicitud y aplica el seed empaquetado cuando la base de datos está vacía y la configuración no se ha completado.

Autenticación

Los comandos que se conectan a una instancia EmDash en ejecución 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. Dev bypass — si la URL es localhost y no hay token disponible, se autentica automáticamente a través del endpoint de dev bypass

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 token.

Flags comunes

Los flags de conexión varían según el comando. Los comandos agrupados abajo significan cada subcomando de ese grupo.

Salida

Cuando un comando escribe resultados en un terminal interactivo, los formatea para lectura. Los comandos listados con --json arriba escriben JSON en bruto cuando se establece el flag o su salida se redirige por pipe. 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 plantilla en package.json. El comando ejecuta las migraciones principales y luego aplica el archivo SQL opcional nombrado por emdash.schema. Ejecuta emdash seed por separado para datos seed JSON.

npx emdash init [options]

Sin --force, una base de datos inicializada se deja sin cambios. Este comando abre un archivo SQLite local directamente; usa emdash migrate para migraciones 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, migración, collection, tabla y usuario. Si el proyecto tiene una configuración Wrangler, el comando también comprueba que un Cron Trigger y un manejador EmDash scheduled() estén configurados juntos.

npx emdash doctor [options]

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

emdash seed

Valida o aplica un seed JSON a una base de datos SQLite local. El comando usa la ruta posicional cuando se proporciona, luego .emdash/seed.json, luego la ruta emdash.seed de package.json.

npx emdash seed [path] [options]

Aplicar un seed ejecuta primero las migraciones principales. 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 principales emitido por una build de Astro.

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

Por defecto, el comando descubre la raíz del proyecto y lee .emdash/migrations.json. Valida el manifiesto frente al paquete EmDash instalado del proyecto, resuelve el ejecutor local del proyecto del adaptador e imprime el destino inmutable antes de cualquier SQL.

Opciones

La aplicación y la liberación del bloqueo legibles e interactivas piden confirmación. La aplicación o liberación del bloqueo no interactiva, y toda aplicación o liberación del bloqueo con --json, requieren la huella exacta impresa para el destino. No hay down ni --dry-run; usa --check para determinar si se requiere trabajo.

Códigos de salida

Consulta Manage Core Database Migrations para el orden de despliegue, las credenciales del destino y el bloqueo de migración D1.

emdash dev (obsoleto)

El comando legacy inicializa y migra una base de datos SQLite local antes de iniciar Astro. Ese comportamiento no usa el adaptador de base de datos configurado por el sitio y es incompatible con el desarrollo de Cloudflare D1. Las invocaciones existentes ahora imprimen una advertencia de obsolescencia antes de hacer cualquier trabajo de base de datos.

emdash types

Genera tipos TypeScript a partir del esquema de una instancia 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://my-site.pages.dev

# Custom output path
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 schema.json junto a él como referencia

emdash login

Inicia sesión en una instancia EmDash usando 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 el dev bypass automáticamente
3. De lo contrario inicia OAuth Device Flow — muestra un código y abre tu navegador. Tras introducir el código, la página de administración lista los permisos que recibirá la CLI, y cualquier permiso solicitado que tu rol no permita, antes de que apruebes.
4. Sondea la autorización y luego 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 correo, nombre, rol, método de autenticación y URL de la instancia.

emdash content

Gestiona elementos de contenido. Todos los subcomandos usan la API remota a través de 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 datos mediante exactamente uno de --data, --file o --stdin. Los elementos nuevos se publican automáticamente a menos 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 siguientes pasos 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 leer e inténtalo de nuevo.

Si alguien tiene la entrada abierta en la administración, el servidor devuelve 409 con código ENTRY_LOCKED y un mensaje que nombra al titular. Espera a que termine, o pasa --override-lock. El mismo flag 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 suave 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 de la papelera.

content translations <collection> <id>

Lista cada traducción del grupo de traducción de la entrada:

npx emdash content translations posts 01ABC123

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

emdash schema

Gestiona collections y campos.

schema list

npx emdash schema list

Lista todas las collections.

schema get <collection>

npx emdash schema get posts

Muestra una collection 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 a menos 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 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 "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 de contenido para una collection o para cada collection de contenido. Úsalo tras 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 uno de --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 collection.

Los resultados estructurados complete, partial y stale salen con 0; los resultados estructurados failed salen con 1. La automatización y los trabajos cron deben usar --json y analizar status, failedSourceCount, skippedSourceCount y los resúmenes por collection en lugar de tratar la 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 a 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 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 por flags incorrectos, PACKAGE_FILE_REQUIRED cuando una importación reanudada aún necesita el archivo del paquete, y UNKNOWN_ERROR.

Los comandos reintentan fallos de red y respuestas 408, 429 y 5xx con 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 avanza hasta completarla y descarga el archivo de paquete archivo a archivo. Comprueba que el manifiesto descargado coincida con el digest del paquete de la exportación, y falla con TRANSFER_PACKAGE_DIGEST_MISMATCH antes de escribir nada si no coincide. Comprueba el tamaño y el digest 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 reutilizan, y el comando informa cuántos reutilizó. Ambos se eliminan cuando se escribe el paquete. El archivo de progreso se ignora cuando se escribió para otra URL u otra configuración de comentarios, o cuando su exportación falló o expiró; el comando inicia entonces una nueva exportación.

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

site import <file>

Importa un paquete en dos pasos. Analízalo primero y luego confirma el 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 todo el archivo del paquete localmente, luego encuentra 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 digests del paquete y del plan, recuentos de registros, tamaños, la elección de título y eslogan, cada principal y su mapeo, las transformaciones bajo «Differences from the source site», las advertencias y los bloqueadores. Si una importación anterior del mismo paquete falló, se canceló o abandonó, o expiró, el comando avisa e inicia una nueva importación.

Las decisiones se almacenan con la importación, de modo que una ejecución posterior de --analyze sin flags de decisión las conserva. Cada cambio de decisiones produce un nuevo digest del plan. 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 digest coincide con el plan actual, luego la avanza hasta completarla 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 nuevo digest.

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 informa 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 el mensaje; el mensaje también se omite con --json o cuando stdout no es un terminal. Cuando stdin no es un terminal y no aplica ninguno, el comando falla con INVALID_ARGUMENT. Rechazar el mensaje no cambia nada y sale con código 1. El resultado JSON de ambos es { operationId, state, operation }.

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

emdash plugin

Crea, valida, empaqueta y publica plugins de EmDash. El inicio de sesión en el marketplace es independiente del inicio de sesión en una instancia CMS.

plugin init

Genera el andamiaje de un plugin sandboxed o nativo:

npx emdash plugin init --dir ./my-plugin --name my-plugin --format sandboxed

plugin bundle

Valida un plugin y crea su tarball del marketplace:

npx emdash plugin bundle --dir ./my-plugin --outDir ./artifacts

plugin validate

Ejecuta la misma validación que plugin bundle sin crear un tarball:

npx emdash plugin validate --dir ./my-plugin

El --dir opcional selecciona el directorio del plugin y por defecto es el directorio actual.

plugin publish

Sube un bundle al marketplace y, por defecto, espera su resultado de procesamiento:

npx emdash plugin publish --tarball ./dist/my-plugin-1.0.0.tar.gz

Proporciona --tarball, o pasa --build para compilar desde --dir primero.

plugin login

Autentica en el marketplace mediante GitHub device flow. --registry selecciona un marketplace distinto y por defecto es https://marketplace.emdashcms.com.

npx emdash plugin login

plugin logout

Elimina la credencial del marketplace guardada. El --registry opcional debe identificar el mismo marketplace usado para el inicio de sesión.

npx emdash plugin logout

emdash export-seed

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

La base de datos debe tener cada migración conocida por la versión de EmDash instalada. Si el comando informa migraciones pendientes, ejecuta npx emdash migrate y exporta de nuevo. 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 solo lectura y nunca aplica migraciones por sí misma.

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

Opciones

Formato de salida

El archivo seed exportado incluye:

• Settings: Título del sitio, eslogan, enlaces sociales
• Collections: Todas las definiciones de collection con campos
• Block types: Cada versión retenida y el puntero de versión activa de cada tipo
• Taxonomies: Definiciones de taxonomía y términos
• Menus: Menús de navegación con elementos
• Redirects: Reglas de redirección con estado 301, 302, 307 o 308
• Widget Areas: Áreas de widgets y widgets
• Sections: Bloques de contenido reutilizables
• Content (si se solicita): Entradas con referencias $media y sintaxis $ref: para portabilidad

Las entradas programadas se exportan como borradores, porque un seed no tiene campo para una 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 sections cuyo slug contiene caracteres distintos de letras minúsculas, dígitos y guiones.

URLs 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 llegar. Pasa la URL pública del sitio de origen para escribir URLs 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 el seed, y la URL no debe apuntar a localhost ni a una dirección de red privada, desde las que emdash seed se niega a descargar. Sin --media-base-url, las URLs $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 archivo, y los subcampos de imagen de los repeaters, se exportan como referencias $media. Las imágenes dentro de campos Portable Text conservan su ID de medio y URL almacenados, que no se resuelven en un sitio distinto.

emdash secrets

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

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 por pipe a tu almacén de secretos, o escríbela directamente en tu archivo .env local con --write. Wrangler y el plugin Vite de Cloudflare leen ese archivo en el desarrollo local. Un servidor Node independiente no carga .env automáticamente; cárgalo a través del gestor de procesos o proporciona la clave a través del entorno del proceso del servidor. La guía de despliegue de 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, antepone la clave generada al valor existente y separa las claves con una coma. EmDash cifra valores nuevos con la primera clave y usa entradas anteriores para el descifrado por kid. Vuelve a guardar cada secreto de plugin antes de eliminar una clave antigua. EmDash no lista actualmente los ID de clave que aún usan 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 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 de una clave:

npx emdash secrets fingerprint emdash_enc_v1_...

emdash auth (obsoleto)

auth secret

Genera un valor legacy EMDASH_AUTH_SECRET:

npx emdash auth secret

Las instalaciones existentes pueden conservar esta variable para preservar hashes estables de IP de comentaristas. No cifra secretos de plugins.

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 tras cambios de esquema realizados a través del sitio de desarrollo en ejecución. Las declaraciones aumentan 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 trabajo 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 TypeScript independientes. Úsalo cuando el esquema viva en una instancia EmDash remota, cuando las herramientas necesiten 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 collection independientes y no aumenta EmDashCollections. Solo cambia cuando ejecutas emdash types; emdash-env.d.ts usa aumentación de módulos y se actualiza como parte del desarrollo local.

.emdash/schema.json

El comando también escribe una exportación de esquema en bruto llamada schema.json junto a la salida 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 comandos habituales como scripts de package.json por 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 listados en su tabla de códigos de salida. emdash site import usa 2 cuando el plan de importación tiene bloqueadores.