Riferimento della CLI

La CLI di EmDash fornisce comandi per la configurazione del database, la generazione dei tipi, la creazione e la modifica dei contenuti, la gestione dello schema, i media e l’esportazione e l’importazione dei siti.

Installazione

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

npm install emdash

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

Avvia il tuo sito con il relativo 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, prima del completamento della configurazione, applica una sola volta lo schema e la struttura del seed incluso. I contenuti di esempio del seed vengono applicati solo quando un amministratore li sceglie nella procedura guidata di configurazione.

Autenticazione

I comandi che si connettono 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 in ~/.config/emdash/auth.json (salvate da emdash login)
4. Bypass di sviluppo — se l’URL è localhost e non è disponibile alcun token, si autentica automaticamente tramite l’endpoint di bypass di sviluppo

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

Flag comuni

I flag di connessione variano in base al comando. I comandi raggruppati qui sotto indicano tutti i sottocomandi di quel gruppo.

Output

Quando un comando scrive i risultati in un terminale interattivo, li formatta per la lettura. I comandi elencati sopra con --json scrivono JSON grezzo quando il flag è impostato o il loro output viene inviato in pipe. emdash migrate emette JSON solo con la sua opzione esplicita --json.

Comandi

emdash init

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

npx emdash init [options]

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

emdash doctor

Controlla un database SQLite locale alla ricerca di problemi di connessione, migrazioni, collezioni, tabelle e utenti. Se il progetto ha una configurazione Wrangler, il comando verifica anche che un Cron Trigger e un gestore scheduled() di EmDash siano configurati insieme.

npx emdash doctor [options]

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

emdash seed

Convalida 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 di package.json.

npx emdash seed [path] [options]

L’applicazione di un seed esegue prima le migrazioni del core. Usa --validate nell’integrazione continua quando devi controllare il file senza aprire né creare il database.

emdash migrate

Controlla o applica l’insieme di migrazioni del core emesso da una build di 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 individua la radice del progetto e legge .emdash/migrations.json. Convalida il manifest rispetto al pacchetto EmDash installato nel progetto, risolve l’esecutore locale al progetto dell’adattatore e stampa la destinazione immutabile prima di qualsiasi SQL.

Opzioni

L’applicazione e il rilascio del blocco in modalità interattiva e leggibile da una persona chiedono conferma. L’applicazione o il rilascio del blocco in modalità non interattiva, e ogni applicazione o rilascio con --json, richiedono l’impronta esatta stampata per la destinazione. Non esistono down né --dry-run; usa --check per stabilire se serve del lavoro.

Codici di uscita

Consulta Gestire le migrazioni del database del core per l’ordine di deployment, le credenziali della destinazione e il blocco di migrazione di D1.

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://example.com

# Custom output path
npx emdash types --output src/types/emdash.ts

Comportamento

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

emdash login

Accede a un’istanza EmDash usando l’OAuth Device Flow.

npx emdash login [options]

Opzioni

Comportamento

1. Individua gli endpoint di autenticazione dell’istanza
2. Se è localhost e non è configurata alcuna autenticazione, usa automaticamente il bypass di sviluppo
3. In caso contrario avvia l’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 gli eventuali permessi richiesti che il tuo ruolo non consente, prima che tu approvi.
4. Interroga l’autorizzazione, quindi salva le credenziali in ~/.config/emdash/auth.json

Le credenziali salvate vengono 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 attualmente autenticato.

npx emdash whoami [options]

Opzioni

Mostra e-mail, 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 una sola tra le opzioni --data, --file o --stdin. I nuovi elementi vengono pubblicati automaticamente, a meno che non sia impostato --draft.

content update <collection> <id>

Devi fornire il token _rev ottenuto da un get precedente per dimostrare di aver visto lo stato corrente. Questo impedisce di sovrascrivere modifiche che non hai visto. I passaggi seguenti leggono un elemento e 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 dopo il tuo get, il server restituisce 409 Conflict: rileggilo e riprova.

Se qualcuno ha aperto la voce nell’amministrazione, il server restituisce 409 con il codice ENTRY_LOCKED e un messaggio che indica chi detiene il blocco. Attendi che abbia finito, 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 in modo logico l’elemento di contenuto (lo sposta nel cestino).

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

content publish <collection> <id>

npx emdash content publish posts 01ABC123

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

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

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

content restore <collection> <id>

npx emdash content restore posts 01ABC123

Ripristina un elemento di contenuto spostato nel cestino.

content translations <collection> <id>

Elenca tutte le traduzioni nel gruppo di traduzione della voce:

npx emdash content translations posts 01ABC123

Il risultato include ID, locale, slug e stato di ogni traduzione, e indica se si tratta della voce richiesta.

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

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

media repair-usage

Ripara gli indici di utilizzo dei media dei contenuti per una collezione o per tutte le collezioni di contenuto. Usalo dopo importazioni o scritture dirette nel database quando la copertura dell’utilizzo è obsoleta o non attendibile.

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

Passa una sola tra le opzioni --collection o --all. La riparazione da remoto 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 sui siti di grandi dimensioni. Preferisci --collection quando devi riparare una sola collezione.

I risultati di riparazione strutturati complete, partial e stale terminano con 0; i risultati strutturati failed terminano con 1. Automazioni e job cron dovrebbero usare --json e analizzare status, failedSourceCount, skippedSourceCount e i riepiloghi per collezione, invece di considerare il codice di 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 tutte le sue voci.

emdash site

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

Il token richiede lo scope admin, che il token di emdash login possiede, oppure gli scope di trasferimento corrispondenti: transfer:export per esportare, e transfer:analyze e transfer:execute per importare. Un token che ne è privo fallisce con INSUFFICIENT_SCOPE.

I messaggi di avanzamento 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’importazione ripresa ha ancora bisogno 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’esportazione, la fa avanzare fino al completamento e scarica il file di pacchetto file per file. Verifica che il manifest scaricato corrisponda al digest del pacchetto dell’esportazione e, se non corrisponde, fallisce con TRANSFER_PACKAGE_DIGEST_MISMATCH prima di scrivere qualsiasi cosa. Controlla la dimensione e il 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 i propri progressi in <output>.partial.json e i file scaricati nella directory <output>.parts/. Esegui di nuovo lo stesso comando dopo un’interruzione per riprendere la stessa esportazione; i file già scaricati vengono controllati e riutilizzati, e il comando indica quanti ne ha riutilizzati. Entrambi vengono eliminati quando il pacchetto è stato scritto. Il file dei progressi viene ignorato quando è stato scritto per un altro URL o per un’altra impostazione dei commenti, oppure quando la sua esportazione è fallita o scaduta; in tal caso il comando avvia una nuova esportazione.

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 stampato dall’analisi:

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

--analyze verifica localmente l’intero file del pacchetto, poi trova l’importazione esistente dello stesso pacchetto del sito oppure ne crea una. Carica i file che il sito non ha ancora, esegue l’analisi e stampa il piano: i digest del pacchetto e del piano, il numero di record, le dimensioni, la scelta di titolo e sottotitolo, ogni principal e la sua associazione, le trasformazioni sotto «Differences from the source site», gli avvisi e i blocchi. Se una precedente importazione dello stesso pacchetto è fallita, è stata annullata o abbandonata, o è scaduta, il comando avvisa e avvia una nuova importazione.

Le decisioni vengono memorizzate con l’importazione, quindi 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’importazione solo quando il digest corrisponde al piano corrente, poi la 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 indica se il receiptDigest della ricevuta corrisponde al suo contenuto.

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

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

I comandi di importazione terminano con questi codici:

emdash export-seed

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

Il database deve avere tutte le migrazioni note alla versione di 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 di EmDash più recente, aggiorna la versione installata prima di esportare. L’esportazione 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 di seed esportato comprende:

• Impostazioni: titolo del sito, sottotitolo, link social
• Collezioni: tutte le definizioni delle collezioni con i campi
• Tipi di blocco: ogni versione conservata e il puntatore alla versione attiva di ciascun tipo
• Tassonomie: definizioni delle tassonomie e termini
• Menu: menu di navigazione con le voci
• Reindirizzamenti: regole di reindirizzamento con stato 301, 302, 307 o 308
• Aree widget: aree widget e widget
• Sezioni: blocchi di contenuto riutilizzabili
• Contenuti (se richiesti): 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 l’orario di pubblicazione. L’esportazione omette, con un avviso su stderr, tutto ciò che emdash seed rifiuterebbe: le regole di reindirizzamento con stato 410 o 451, le regole aggiuntive che condividono la stessa origine (possibile nei database meno recenti) e le sezioni 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 ha bisogno di un URL http o https assoluto che possa raggiungere. 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 né a un indirizzo di rete privata, dai quali 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’esportazione stampa un avviso su stderr.

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

emdash secrets

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

secrets generate

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

npx emdash secrets generate

Stampa la nuova chiave su stdout. Inviala in pipe al tuo archivio dei segreti, oppure scrivila direttamente nel tuo 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 del processo del server. La guida al deployment su 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 in base al kid. Salva di nuovo ogni segreto dei plugin prima di rimuovere una chiave vecchia. Al momento EmDash non elenca gli ID di chiave ancora usati dalle impostazioni memorizzate, quindi tieni un inventario delle credenziali che salvi di nuovo e verifica ogni integrazione prima di rimuovere la sua vecchia chiave.

secrets fingerprint <key>

Stampa l’impronta (kid) di 8 caratteri di una chiave senza esporne il valore. È utile in CI per verificare che sia stata distribuita la chiave giusta. Il comando seguente stampa l’impronta di una chiave:

npx emdash secrets fingerprint emdash_enc_v1_...

File generati

emdash-env.d.ts

L’integrazione Astro genera emdash-env.d.ts nella radice del progetto all’avvio del server di sviluppo locale. Aggiorna il file dopo le modifiche allo schema effettuate tramite il sito di sviluppo in esecuzione. Le dichiarazioni estendono EmDashCollections, quindi chiamate come getEmDashCollection("posts") deducono i campi definiti nel database locale.

Questo file è automatico e fa parte del flusso di sviluppo locale di Astro. Non devi 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 si trova su un’istanza EmDash remota, quando gli strumenti hanno bisogno 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 collezione autonome e non estende EmDashCollections. Cambia solo quando esegui emdash types; emdash-env.d.ts usa l’augmentation dei moduli e viene aggiornato come parte dello sviluppo locale.

.emdash/schema.json

Il comando scrive anche un’esportazione dello schema grezza, chiamata 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 i comandi più 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 importazione presenta dei blocchi.