Referencia de la CLI

La CLI de EmDash proporciona comandos para gestionar una instancia de EmDash CMS: configuración de la base de datos, generación de tipos, CRUD de contenido, gestión del esquema, medios y mucho más.

Instalación

La CLI se incluye con el paquete emdash:

npm install emdash

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

Autenticación

Los comandos que se comunican con una instancia de EmDash en ejecución (todos excepto init, seed, export-seed y auth secret) 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 en ~/.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 mediante el endpoint de bypass de desarrollo

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

Flags comunes

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

Salida

Cuando stdout es un TTY, la CLI muestra los resultados con formato legible mediante consola. Cuando se redirige o se establece --json, produce JSON sin formato en stdout, adecuado para jq u otras herramientas.

Comandos

emdash init

Inicializa la base de datos con el esquema principal y datos de plantilla opcionales.

npx emdash init [options]

Opciones

Comportamiento

1. Lee la configuración emdash de package.json
2. Crea el archivo de base de datos si es necesario
3. Ejecuta las migraciones principales (crea tablas de sistema)
4. Ejecuta schema.sql de la plantilla si está configurado
5. Ejecuta seed.sql de la plantilla si está configurado

emdash dev

Inicia el servidor de desarrollo con configuración automática de la 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 se establece --types, genera tipos TypeScript desde una instancia remota (URL de EMDASH_URL o emdash.url en package.json)
3. Inicia el servidor de desarrollo de Astro con EMDASH_DATABASE_URL configurado

emdash types

Genera tipos TypeScript desde el esquema de una instancia de 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 los tipos en el archivo de salida
4. Escribe schema.json junto al archivo como referencia

emdash login

Inicia sesión en una instancia de 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 bypass de desarrollo automáticamente
3. En caso contrario, inicia OAuth Device Flow: muestra un código y abre el navegador
4. Espera la autorización y guarda las credenciales en ~/.config/emdash/auth.json

Las credenciales guardadas se usan automáticamente en todos los comandos posteriores dirigidos 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 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 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 demostrar que has visto lo que estás sobrescribiendo.

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 las opciones: --data, --file o --stdin.

content update <collection> <id>

Como un editor de archivos que requiere leer antes de escribir: debes proporcionar el token _rev de un get previo para demostrar que has visto el estado actual. Esto evita sobrescribir accidentalmente cambios que no has visto.

# 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 inténtalo de nuevo.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Hace borrado lógico 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 de la papelera.

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

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

Aplica un archivo seed a la base de datos. Este comando trabaja directamente sobre un archivo SQLite local (no necesita servidor en ejecución).

npx emdash seed [path] [options]

Argumentos

Opciones

Resolución del archivo seed

El comando busca archivos seed en este orden:

1. Argumento posicional (si se proporciona)
2. .emdash/seed.json (convención)
3. Ruta del campo emdash.seed en package.json

emdash export-seed

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

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 colecciones con campos
• Taxonomies: Definiciones de taxonomías y términos
• Menus: Menús de navegación con elementos
• Widget Areas: Áreas de widgets y widgets
• Content (si se solicita): Entradas con referencias $media y sintaxis $ref: para portabilidad

emdash auth secret

Genera un secreto de autenticación seguro para tu despliegue.

npx emdash auth secret

Produce un secreto aleatorio adecuado para EMDASH_AUTH_SECRET.

Archivos generados

.emdash/types.ts

Interfaces TypeScript generadas por emdash types:

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

Exportación del esquema sin formato para herramientas:

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

Variables de entorno

Scripts de package

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

Códigos de salida