Riferimento CLI

La CLI di EmDash fornisce comandi per gestire un’istanza di EmDash CMS — configurazione database, generazione tipi, CRUD contenuti, gestione schema, media e altro ancora.

Installazione

La CLI è inclusa nel pacchetto emdash. Installala con il seguente comando:

npm install emdash

Esegui i comandi con npx emdash o aggiungi script a package.json. Il binario è disponibile anche come em per brevità.

Autenticazione

I comandi che comunicano con un’istanza EmDash in esecuzione risolvono l’autenticazione in questo ordine:

1. Flag --token — token esplicito sulla riga di comando
2. Variabile d’ambiente EMDASH_TOKEN
3. Credenziali memorizzate da ~/.config/emdash/auth.json (salvate da emdash login)
4. Bypass dev — se l’URL è localhost e non è disponibile alcun token, si autentica automaticamente tramite l’endpoint di bypass dev

La maggior parte dei comandi accetta i flag --url (predefinito http://localhost:4321) e --token. Quando si punta a un server di sviluppo locale, non è necessario alcun token.

Flag comuni

Questi flag sono disponibili su tutti i comandi remoti:

Output

Quando stdout è un TTY, la CLI stampa i risultati formattati con consola. Quando viene utilizzata con piping o quando --json è impostato, genera JSON grezzo su stdout — adatto per jq o altri strumenti.

Comandi

emdash dev

Avvia il server di sviluppo con configurazione automatica del database.

npx emdash dev [options]

Opzioni

Esempi

# Avvia server di sviluppo
npx emdash dev

# Porta personalizzata
npx emdash dev --port 3000

# Genera tipi da remoto prima dell'avvio
npx emdash dev --types

Comportamento

1. Controlla ed esegue le migrazioni del database in sospeso
2. Se --types è impostato, genera tipi TypeScript da un’istanza remota (URL da env EMDASH_URL o emdash.url in package.json)
3. Avvia il server di sviluppo Astro con EMDASH_DATABASE_URL impostato

emdash types

Genera tipi TypeScript dallo schema di un’istanza EmDash in esecuzione.

npx emdash types [options]

Opzioni

Esempi

# Genera tipi dal server di sviluppo locale
npx emdash types

# Genera da istanza remota
npx emdash types --url https://my-site.pages.dev

# Percorso output personalizzato
npx emdash types --output src/types/emdash.ts

Comportamento

1. Recupera lo schema dall’istanza
2. Genera definizioni di tipi TypeScript
3. Scrive i tipi nel file di output
4. Scrive schema.json accanto per riferimento

emdash login

Accedi a un’istanza EmDash utilizzando OAuth Device Flow.

npx emdash login [options]

Opzioni

Comportamento

1. Scopre gli endpoint di autenticazione dall’istanza
2. Se localhost e nessuna autenticazione configurata, utilizza automaticamente il bypass dev
3. Altrimenti avvia OAuth Device Flow — mostra un codice e apre il browser
4. Interroga per l’autorizzazione, quindi salva le credenziali in ~/.config/emdash/auth.json

Le credenziali salvate vengono utilizzate automaticamente da tutti i comandi successivi che puntano alla stessa istanza.

emdash logout

Disconnettiti e rimuovi le credenziali memorizzate.

npx emdash logout [options]

Opzioni

emdash whoami

Mostra l’utente attualmente autenticato.

npx emdash whoami [options]

Opzioni

Mostra email, nome, ruolo, metodo di autenticazione e URL dell’istanza.

emdash content

Gestisce gli elementi di contenuto. Tutti i sottocomandi utilizzano l’API remota tramite 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 risposta include un token _rev. Passalo a content update per confermare di aver visto lo stato corrente prima di sovrascriverlo.

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

Fornisci i dati tramite esattamente una tra --data, --file o --stdin. I nuovi elementi vengono pubblicati automaticamente a meno che --draft non sia impostato.

content update <collection> <id>

Devi fornire il token _rev da un get precedente per dimostrare di aver visto lo stato corrente. Questo impedisce di sovrascrivere modifiche che non hai visto. I seguenti passaggi leggono un elemento e poi lo aggiornano con quel token:

# 1. Leggi l'elemento, annota il _rev
npx emdash content get posts 01ABC123

# 2. Aggiorna con il _rev dal passaggio 1
npx emdash content update posts 01ABC123 \
  --rev MToyMDI2LTAyLTE0... \
  --data '{"title": "Updated"}'

Se l’elemento è cambiato dal tuo get, il server restituisce 409 Conflict — rileggi e riprova.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Elimina con soft-delete l’elemento di contenuto (sposta nel cestino).

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

Ripristina un elemento di contenuto eliminato.

emdash schema

Gestisce collezioni e campi.

schema list

npx emdash schema list

Elenca tutte le collezioni.

schema get <collection>

npx emdash schema get posts

Mostra una collezione con tutti i suoi campi.

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

Richiede conferma a meno che --force non sia impostato.

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

Gestisce gli elementi multimediali.

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

Ricerca full-text sui contenuti.

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

emdash taxonomy

Gestisce tassonomie e termini.

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

Gestisce i menu di navigazione.

menu list

npx emdash menu list

menu get <name>

npx emdash menu get primary

Restituisce il menu con tutti i suoi elementi.

emdash export-seed

Esporta schema database e contenuto come file seed. Funziona direttamente su un file SQLite locale.

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

Opzioni

Formato output

Il file seed esportato include:

• Impostazioni: Titolo sito, slogan, link social
• Collezioni: Tutte le definizioni di collezione con campi
• Tassonomie: Definizioni di tassonomia e termini
• Menu: Menu di navigazione con elementi
• Aree widget: Aree widget e widget
• Contenuto (se richiesto): Voci con riferimenti $media e sintassi $ref: per portabilità

emdash secrets generate

Genera una EMDASH_ENCRYPTION_KEY per il tuo deployment. La chiave viene utilizzata per crittografare i segreti dei plugin a riposo.

npx emdash secrets generate

Stampa la nuova chiave su stdout. Indirizzala al tuo archivio segreti, o scrivila direttamente in un file di sviluppo con --write. I seguenti comandi scrivono la chiave in .dev.vars o .env:

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

--write rifiuta di sovrascrivere una voce esistente senza --force. Sostituire una chiave in un deployment con dati crittografati esistenti renderà quei segreti illeggibili, quindi la protezione è intenzionale.

emdash secrets fingerprint <key>

Stampa l’impronta digitale di 8 caratteri (kid) di una chiave senza esporre il suo valore. Questo è utile in CI per verificare che sia stata distribuita la chiave corretta. Il seguente comando stampa l’impronta digitale di una chiave:

npx emdash secrets fingerprint emdash_enc_v1_...

File generati

.emdash/types.ts

Il comando emdash types genera interfacce TypeScript per ogni collezione:

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

Il comando scrive anche un’esportazione schema grezza per gli strumenti:

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

Variabili d’ambiente

Script di package

Aggiungi i comandi CLI come script package.json per comodità:

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

Codici di uscita