Riferimento della CLI

La CLI di EmDash fornisce comandi per la configurazione del database, la generazione di tipi, la creazione e modifica dei contenuti, la gestione dello schema, i media, l’export e l’import del sito e lo sviluppo di plugin.

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

Avvia il sito con lo script del pacchetto, ad esempio pnpm dev. Lo script del pacchetto avvia Astro; l’integrazione EmDash genera emdash-env.d.ts, mentre il runtime esegue le migrazioni in sospeso alla prima richiesta e applica il seed incluso quando il database è vuoto e la configurazione non è stata completata.

Autenticazione

I comandi che si collegano a 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. Dev bypass — se l’URL è localhost e non è disponibile alcun token, autenticazione automatica tramite l’endpoint di dev bypass

I comandi types, whoami, content, schema, media, search, taxonomy, menu e site si collegano a un’istanza in esecuzione. I comandi di autenticazione hanno le proprie opzioni di connessione. Quando si punta a un server di sviluppo locale, non serve un token.

Flag comuni

I flag di connessione variano per comando. I comandi raggruppati sotto indicano ogni sottocomando di quel gruppo.

Output

Quando un comando scrive risultati su un terminale interattivo, li formatta per la lettura. I comandi elencati con --json sopra scrivono JSON grezzo quando il flag è impostato o l’output è pipeato. emdash migrate emette JSON solo con la sua opzione esplicita --json.

Comandi

emdash init

Inizializza un database SQLite locale dai metadati del template in package.json. Il comando esegue le migrazioni core, poi applica il file SQL opzionale indicato da emdash.schema. Esegui emdash seed separatamente per i dati seed JSON.

npx emdash init [options]

Senza --force, un database inizializzato resta invariato. Questo comando apre direttamente un file SQLite locale; usa emdash migrate per le migrazioni D1, PostgreSQL, libSQL o Hyperdrive gestite dal deployment.

emdash doctor

Controlla un database SQLite locale per problemi di connessione, migrazione, collection, tabella e utente. Se il progetto ha una configurazione Wrangler, il comando verifica anche che un Cron Trigger e un handler EmDash scheduled() siano configurati insieme.

npx emdash doctor [options]

Il comando riporta ogni controllo come superato, avviso o errore e termina con codice diverso da zero quando un controllo fallisce.

emdash seed

Valida o applica un seed JSON a un database SQLite locale. Il comando usa il percorso posizionale se fornito, poi .emdash/seed.json, poi il percorso emdash.seed da package.json.

npx emdash seed [path] [options]

Applicare un seed esegue prima le migrazioni core. Usa --validate nell’integrazione continua quando devi controllare il file senza aprire o creare il database.

emdash migrate

Controlla o applica l’insieme di migrazioni core emesso da una build Astro.

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

Per impostazione predefinita il comando scopre la root del progetto e legge .emdash/migrations.json. Valida il manifesto rispetto al pacchetto EmDash installato del progetto, risolve l’executor locale al progetto dell’adapter e stampa il target immutabile prima di qualsiasi SQL.

Opzioni

L’applicazione e il rilascio del lock leggibili e interattivi chiedono conferma. L’applicazione o il rilascio del lock non interattivi, e ogni applicazione o rilascio del lock con --json, richiedono l’impronta esatta stampata per il target. Non esiste down né --dry-run; usa --check per determinare se è richiesto lavoro.

Codici di uscita

Vedi Manage Core Database Migrations per l’ordine di deployment, le credenziali del target e il lock di migrazione D1.

emdash dev (deprecato)

Il comando legacy inizializza e migra un database SQLite locale prima di avviare Astro. Quel comportamento non usa l’adapter del database configurato dal sito ed è incompatibile con lo sviluppo Cloudflare D1. Le invocazioni esistenti ora stampano un avviso di deprecazione prima di qualsiasi lavoro sul database.

emdash types

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

npx emdash types [options]

Opzioni

Esempi

# 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

Comportamento

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

emdash login

Accede a un’istanza EmDash usando OAuth Device Flow.

npx emdash login [options]

Opzioni

Comportamento

1. Scopre gli endpoint di autenticazione dall’istanza
2. Se è localhost e non c’è autenticazione configurata, usa automaticamente il dev bypass
3. Altrimenti avvia OAuth Device Flow — mostra un codice e apre il browser. Dopo aver inserito il codice, la pagina di amministrazione elenca i permessi che la CLI riceverà, e qualsiasi permesso richiesto che il tuo ruolo non consente, prima che approvi.
4. Interroga l’autorizzazione, poi salva le credenziali in ~/.config/emdash/auth.json

Le credenziali salvate sono usate automaticamente da tutti i comandi successivi che puntano alla stessa istanza.

emdash logout

Esce e rimuove le credenziali memorizzate.

npx emdash logout [options]

Opzioni

emdash whoami

Mostra l’utente autenticato corrente.

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 usano 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 uno di --data, --file o --stdin. I nuovi elementi sono pubblicati automaticamente a meno che non sia impostato --draft.

content update <collection> <id>

Devi fornire il token _rev da un get precedente per dimostrare di aver visto lo stato corrente. Questo evita di sovrascrivere modifiche che non hai visto. I passaggi seguenti leggono un elemento, poi lo aggiornano con quel 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"}'

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

Se qualcuno ha la voce aperta nell’admin, il server restituisce 409 con codice ENTRY_LOCKED e un messaggio che nomina il titolare. Attendi che finisca, oppure passa --override-lock. Lo stesso flag è disponibile su content delete, content publish, content unpublish e content schedule.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Elimina soft l’elemento di contenuto (lo sposta nel cestino).

Passa --override-lock per eliminare una voce che un altro editor ha aperta.

content publish <collection> <id>

npx emdash content publish posts 01ABC123

Passa --override-lock per pubblicare una voce che un altro editor ha aperta.

content unpublish <collection> <id>

npx emdash content unpublish posts 01ABC123

Passa --override-lock per annullare la pubblicazione di una voce che un altro editor ha aperta.

content schedule <collection> <id>

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

Passa --override-lock per programmare una voce che un altro editor ha aperta.

content restore <collection> <id>

npx emdash content restore posts 01ABC123

Ripristina un elemento di contenuto cestinato.

content translations <collection> <id>

Elenca ogni traduzione nel gruppo di traduzione della voce:

npx emdash content translations posts 01ABC123

Il risultato include ID, locale, slug, stato di ogni traduzione e se è la voce richiesta.

emdash schema

Gestisce collection e campi.

schema list

npx emdash schema list

Elenca tutte le collection.

schema get <collection>

npx emdash schema get posts

Mostra una collection 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

Chiede conferma a meno che non sia impostato --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

Gestisce gli elementi media.

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

Ripara gli indici di utilizzo dei media dei contenuti per una collection o per ogni collection di contenuti. Usalo dopo import o scritture dirette sul database quando la copertura di utilizzo è obsoleta o non affidabile.

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

Passa esattamente uno di --collection o --all. La riparazione remota richiede un utente Admin e un token di autenticazione con lo scope admin.

La riparazione di tutti i contenuti viene eseguita in modo sincrono e può essere lenta o costosa su siti grandi. Preferisci --collection quando ti serve riparare solo una collection.

I risultati strutturati complete, partial e stale escono con 0; i risultati strutturati failed escono con 1. Automazione e job cron devono usare --json e analizzare status, failedSourceCount, skippedSourceCount e i riepiloghi per collection invece di trattare l’uscita 0 come copertura completa.

emdash search

Ricerca full-text nei 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 site

Esporta un intero sito in un pacchetto sito .emdash e importa un pacchetto in un sito vuoto. La guida al trasferimento del sito spiega cosa contiene un pacchetto, di cosa ha bisogno il sito di destinazione e come leggere un piano di import.

Il token necessita dello scope admin, che ha il token di emdash login, oppure degli scope di trasferimento corrispondenti: transfer:export per esportare, e transfer:analyze e transfer:execute per importare. Un token senza di essi fallisce con INSUFFICIENT_SCOPE.

I messaggi di progresso vanno sempre su stderr e il risultato su stdout. Con --json, o quando stdout non è un terminale, stdout contiene solo il risultato JSON. Un errore viene scritto come { "error": { "code": "…", "message": "…" } }. I codici sono i codici di errore del server, più INVALID_ARGUMENT per flag non validi, PACKAGE_FILE_REQUIRED quando un import ripreso necessita ancora del file del pacchetto, e UNKNOWN_ERROR.

I comandi ritentano gli errori di rete e le risposte 408, 429 e 5xx con backoff.

site export

Esporta il sito e lo scrive in un file di pacchetto:

npx emdash site export --output site.emdash

Il comando avvia un export, lo fa avanzare fino al completamento e scarica il file di pacchetto file per file. Verifica che il manifesto scaricato corrisponda al digest del pacchetto dell’export e fallisce con TRANSFER_PACKAGE_DIGEST_MISMATCH prima di scrivere qualsiasi cosa se non corrisponde. Controlla dimensione e digest SHA-256 di ogni file prima di scriverlo. Il pacchetto viene scritto in <output>.partial e rinominato nel percorso di output quando è completo.

Il comando conserva il progresso in <output>.partial.json e i file scaricati nella directory <output>.parts/. Esegui di nuovo lo stesso comando dopo un’interruzione per riprendere lo stesso export; i file già scaricati vengono controllati e riutilizzati, e il comando riporta quanti ne ha riutilizzati. Entrambi vengono eliminati quando il pacchetto è scritto. Il file di progresso viene ignorato quando è stato scritto per un altro URL o un’altra impostazione dei commenti, o quando il suo export è fallito o scaduto; il comando avvia allora un nuovo export.

Il risultato JSON contiene operationId, output, packageDigest, files, bytes e resumed.

site import <file>

Importa un pacchetto in due passaggi. Analizzalo prima, poi conferma il digest del piano che l’analisi ha stampato:

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

--analyze verifica l’intero file del pacchetto in locale, poi trova l’import esistente dello stesso pacchetto sul sito o ne crea uno. Carica i file che il sito non ha ancora, esegue l’analisi e stampa il piano: i digest del pacchetto e del piano, i conteggi dei record, le dimensioni, la scelta di titolo e tagline, ogni principal e la sua mappatura, le trasformazioni sotto «Differences from the source site», gli avvisi e i bloccanti. Se un import precedente dello stesso pacchetto è fallito, è stato annullato o abbandonato, o è scaduto, il comando avvisa e avvia un nuovo import.

Le decisioni sono memorizzate con l’import, così una successiva esecuzione di --analyze senza flag di decisione le mantiene. Ogni modifica delle decisioni produce un nuovo digest del piano. Le decisioni non possono essere combinate con --plan, e --plan non può essere combinato con --analyze.

--plan <digest> --confirm esegue l’import solo quando il digest corrisponde al piano corrente, poi lo fa avanzare fino al completamento e stampa la ricevuta. Se il piano è cambiato da quando lo hai esaminato, il comando fallisce con TRANSFER_PLAN_DIGEST_MISMATCH; analizza di nuovo e conferma il nuovo digest.

Il risultato JSON di --analyze contiene operationId, state, packageDigest, planDigest, executable e il plan completo. Il risultato JSON di --confirm contiene operationId, state (complete), receipt e receiptDigestValid, che riporta se il receiptDigest della ricevuta corrisponde al suo contenuto.

Queste forme operano su un import tramite il suo ID di operazione:

cancel e abandon chiedono conferma. Passa --yes per saltare il prompt; il prompt viene saltato anche con --json o quando stdout non è un terminale. Quando stdin non è un terminale e nessuno dei due si applica, il comando fallisce con INVALID_ARGUMENT. Rifiutare il prompt non cambia nulla e termina con codice 1. Il risultato JSON di entrambi è { operationId, state, operation }.

I comandi di import escono con questi codici:

emdash plugin

Crea, valida, impacchetta e pubblica plugin EmDash. L’accesso al marketplace è separato dall’accesso a un’istanza CMS.

plugin init

Crea lo scaffold di un plugin sandboxed o nativo:

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

plugin bundle

Valida un plugin e crea il suo tarball del marketplace:

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

plugin validate

Esegue la stessa validazione di plugin bundle senza creare un tarball:

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

Il --dir opzionale seleziona la directory del plugin e ha come predefinita la directory corrente.

plugin publish

Carica un bundle sul marketplace e, per impostazione predefinita, attende il risultato dell’elaborazione:

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

Fornisci --tarball, oppure passa --build per compilare prima da --dir.

plugin login

Autentica al marketplace tramite GitHub device flow. --registry seleziona un marketplace diverso e ha come predefinito https://marketplace.emdashcms.com.

npx emdash plugin login

plugin logout

Rimuove la credenziale del marketplace salvata. Il --registry opzionale deve identificare lo stesso marketplace usato per l’accesso.

npx emdash plugin logout

emdash export-seed

Esporta lo schema del database e i contenuti come file seed. Lavora direttamente su un file SQLite locale.

Il database deve avere ogni migrazione nota alla versione EmDash installata. Se il comando segnala migrazioni in sospeso, esegui npx emdash migrate, poi esporta di nuovo. Se il database è stato migrato da una versione EmDash più recente, aggiorna la versione installata prima di esportare. L’export apre il database in sola lettura e non applica mai migrazioni da sé.

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

Opzioni

Formato di output

Il file seed esportato include:

• Settings: Titolo del sito, tagline, link social
• Collections: Tutte le definizioni di collection con campi
• Block types: Ogni versione trattenuta e il puntatore della versione attiva di ciascun tipo
• Taxonomies: Definizioni di tassonomia e termini
• Menus: Menu di navigazione con elementi
• Redirects: Regole di redirect con stato 301, 302, 307 o 308
• Widget Areas: Aree widget e widget
• Sections: Blocchi di contenuto riutilizzabili
• Content (se richiesto): Voci con riferimenti $media e sintassi $ref: per la portabilità

Le voci programmate vengono esportate come bozze, perché un seed non ha un campo per un orario di pubblicazione. L’export omette, con un avviso su stderr, tutto ciò che emdash seed rifiuterebbe: regole di redirect con stato 410 o 451, regole extra che condividono una sorgente (possibile in database più vecchi) e section il cui slug contiene caratteri diversi da lettere minuscole, cifre e trattini.

URL dei media

emdash seed scarica ogni URL $media e carica il file nello storage del sito di destinazione, quindi necessita di un URL http o https assoluto raggiungibile. Passa l’URL pubblico del sito di origine per scrivere URL assoluti:

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

Il sito deve servire i propri media da /_emdash/api/media/file/ sotto quell’URL mentre il seed viene applicato, e l’URL non deve puntare a localhost o a un indirizzo di rete privata, da cui emdash seed rifiuta di scaricare. Senza --media-base-url, gli URL $media sono percorsi relativi al sito che emdash seed salta, lasciando i campi vuoti, e l’export stampa un avviso su stderr.

I campi immagine e file, e i sotto-campi immagine dei repeater, vengono esportati come riferimenti $media. Le immagini nei campi Portable Text mantengono l’ID media e l’URL memorizzati, che non si risolvono su un sito diverso.

emdash secrets

Genera e ispeziona la chiave usata per cifrare i secret dei plugin.

secrets generate

Genera un EMDASH_ENCRYPTION_KEY per il tuo deployment. La chiave è usata per cifrare i secret dei plugin a riposo.

npx emdash secrets generate

Stampa la nuova chiave su stdout. Incanalarla nel tuo secret store, oppure scrivila direttamente nel file .env locale con --write. Wrangler e il plugin Vite di Cloudflare leggono quel file nello sviluppo locale. Un server Node autonomo non carica .env automaticamente; caricalo tramite il process manager oppure fornisci la chiave tramite l’ambiente di processo del server. La guida al deployment Node.js mostra il comando locale.

npx emdash secrets generate --write .env

--write rifiuta di sovrascrivere una voce esistente senza --force. Per ruotare un deployment con dati cifrati esistenti, anteponi la chiave generata al valore esistente e separa le chiavi con una virgola. EmDash cifra i nuovi valori con la prima chiave e usa le voci più vecchie per la decifratura tramite kid. Riesalva ogni secret del plugin prima di rimuovere una chiave vecchia. EmDash non elenca attualmente gli ID delle chiavi ancora usati dalle impostazioni memorizzate, quindi tieni un inventario delle credenziali che riesalvi e verifica ogni integrazione prima di rimuovere la sua chiave vecchia.

secrets fingerprint <key>

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

npx emdash secrets fingerprint emdash_enc_v1_...

emdash auth (deprecato)

auth secret

Genera un valore legacy EMDASH_AUTH_SECRET:

npx emdash auth secret

Le installazioni esistenti possono mantenere questa variabile per preservare hash IP dei commentatori stabili. Non cifra i secret dei plugin.

File generati

emdash-env.d.ts

L’integrazione Astro genera emdash-env.d.ts nella root del progetto quando si avvia il server di sviluppo locale. Aggiorna il file dopo modifiche allo schema fatte tramite il sito di sviluppo in esecuzione. Le dichiarazioni aumentano EmDashCollections, così chiamate come getEmDashCollection("posts") inferiscono i campi definiti nel database locale.

Questo file è automatico e appartiene al flusso di sviluppo Astro locale. Non serve eseguire emdash types per crearlo.

.emdash/types.ts

Il comando emdash types recupera lo schema di un’istanza in esecuzione e scrive interfacce TypeScript autonome. Usalo quando lo schema vive su un’istanza EmDash remota, quando gli strumenti necessitano di un file in un percorso personalizzato, o quando il server di sviluppo Astro locale non è in esecuzione:

// 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[]>;
}

L’output remoto contiene interfacce di collection autonome e non aumenta EmDashCollections. Cambia solo quando esegui emdash types; emdash-env.d.ts usa l’augmentation dei moduli e si aggiorna come parte dello sviluppo locale.

.emdash/schema.json

Il comando scrive anche un export grezzo dello schema chiamato schema.json accanto all’output TypeScript selezionato. Con il percorso di output predefinito, il file è .emdash/schema.json:

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

Variabili d’ambiente

Script del pacchetto

Aggiungi comandi comuni come script di package.json per comodità:

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

Codici di uscita generali

La maggior parte dei comandi usa 0 per il successo e 1 per un errore. emdash migrate usa anche i codici 2, 3, 4 e 130 per gli esiti specifici elencati nella sua tabella dei codici di uscita. emdash site import usa 2 quando il piano di import ha bloccanti.