Referencia CLI

La CLI de EmDash proporciona comandos para administrar 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

La CLI está incluida 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 para abreviar.

Autenticación

Los comandos que se comunican con una instancia de 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. Bypass de desarrollo — si la URL es localhost y no hay token disponible, se autentica automáticamente a través del endpoint de bypass de desarrollo

La mayoría de los comandos aceptan flags --url (predeterminado http://localhost:4321) y --token. Al apuntar a un servidor de desarrollo local, no se necesita ningún token.

Flags comunes

Estos flags están disponibles en todos los comandos remotos:

Salida

Cuando stdout es un TTY, la CLI imprime resultados con formato usando consola. Cuando se usa piping o cuando --json está configurado, genera 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. Comprueba y ejecuta migraciones de base de datos pendientes
2. Si --types está configurado, genera tipos TypeScript desde una instancia remota (URL de env EMDASH_URL o emdash.url en package.json)
3. Inicia el servidor de desarrollo Astro con EMDASH_DATABASE_URL configurado

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 de desarrollo 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 tipos en el archivo de salida
4. Escribe schema.json junto para referencia

emdash login

Inicia sesión en una instancia de 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 autenticación configurada, usa bypass de desarrollo automáticamente
3. De lo contrario, inicia OAuth Device Flow — muestra un código y abre tu navegador
4. Consulta la autorización, luego guarda credenciales en ~/.config/emdash/auth.json

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

emdash logout

Cierra 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 email, nombre, rol, método de autenticación y URL de 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 a través de exactamente una de --data, --file o --stdin. Los nuevos elementos se publican automáticamente a menos que --draft esté configurado.

content update <collection> <id>

Debes proporcionar el token _rev de un get previo 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. 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": "Updated"}'

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

Elimina suavemente el 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

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

schema delete <collection>

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

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

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

emdash search

Búsqueda de texto completo en 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 export-seed

Exporta esquema de base de datos y contenido como archivo seed. Funciona directamente en un archivo SQLite local.

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

Opciones

Formato de salida

El archivo seed exportado incluye:

• Configuración: Título del sitio, eslogan, enlaces sociales
• Colecciones: Todas las definiciones de colección con campos
• Taxonomías: Definiciones de taxonomía 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 una 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. Redirígela a tu almacén de secretos, o escríbela directamente en un archivo de desarrollo con --write. Los siguientes comandos escriben la clave en .dev.vars o .env:

npx emdash secrets generate --write .dev.vars
npx emdash secrets generate --write .env

--write rechaza 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:

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

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 package

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

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

Códigos de salida