Riferimento CLI

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

Installazione

Il CLI è incluso nel pacchetto emdash. Installalo 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 usano il client remoto condiviso risolvono l’autenticazione in questo ordine:

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

Questi comandi accettano i flag --url (da EMDASH_URL, con fallback a http://localhost:4321) e --token. I comandi di autenticazione hanno le proprie opzioni di connessione. Quando si punta a un server di sviluppo locale, non è necessario alcun token.

Flag comuni

Questi flag sono disponibili nei comandi che usano il client remoto condiviso:

Output

Quando stdout è un TTY, il CLI stampa i risultati formattati con consola. Quando in pipe o quando --json è impostato, produce 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 dal remoto prima di avviare
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 dalla variabile 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 di output personalizzato
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 un schema.json accanto per riferimento

emdash login

Accedi a un’istanza EmDash usando OAuth Device Flow.

npx emdash login [options]

Opzioni

Comportamento

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

Le credenziali salvate vengono usate automaticamente da tutti i comandi successivi diretti alla stessa istanza.

emdash logout

Disconnetti e rimuovi le credenziali salvate.

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

Gestire 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 sovrascrivere.

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 delle opzioni --data, --file o --stdin. I nuovi elementi vengono auto-pubblicati a meno che --draft sia impostato.

content update <collection> <id>

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

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

# 2. Aggiornare con il _rev del passo 1
npx emdash content update posts 01ABC123 \
  --rev MToyMDI2LTAyLTE0... \
  --data '{"title": "Aggiornato"}'

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

Eliminazione soft dell’elemento di contenuto (spostato 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

Gestire 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 "Articoli del blog"

schema delete <collection>

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

Chiede conferma a meno che --force sia impostato.

schema add-field <collection> <field>

npx emdash schema add-field posts body --type portableText --label "Contenuto del corpo"
npx emdash schema add-field posts featured --type boolean --required

schema remove-field <collection> <field>

npx emdash schema remove-field posts featured

emdash media

Gestire 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 "Un tramonto" --caption "Scattata a 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 del contenuto per una collezione o per tutte le collezioni di contenuto. Usa questo dopo importazioni o scritture dirette sul database quando la copertura d’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 una delle opzioni --collection o --all. La riparazione remota richiede un utente Admin e un token di auth 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 devi riparare solo una collezione.

I risultati di riparazione strutturati complete, partial e stale escono con 0; i risultati failed strutturati escono con 1. L’automazione e i cron job dovrebbero usare --json e parsare status, failedSourceCount, skippedSourceCount e i riepiloghi per collezione invece di trattare l’uscita 0 come copertura completa.

emdash search

Ricerca full-text attraverso i contenuti.

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

emdash taxonomy

Gestire 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

Gestire 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

Esportare lo schema del database e il contenuto come file di seed. Funziona direttamente su un file SQLite locale.

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

Opzioni

Formato di output

Il file di seed esportato include:

• Impostazioni: Titolo del sito, slogan, link social
• Collezioni: Tutte le definizioni di collezione con campi
• Tassonomie: Definizioni di tassonomie 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 la portabilità

emdash secrets generate

Genera un 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. Reindirizzala nel tuo archivio segreti, o scrivila direttamente nel tuo file .env locale con --write. Lo stesso file .env viene letto da Node e, in sviluppo locale, da Wrangler e dal plugin Vite di Cloudflare:

npx emdash secrets generate --write .env

--write rifiuta di sovrascrivere una voce esistente senza --force. Sostituire una chiave in un deployment con dati cifrati 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. Utile in CI per verificare che sia stata deployata la chiave corretta. Il seguente comando stampa l’impronta 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:

// Generato dal CLI EmDash
// Non editare manualmente - esegui `emdash types` per rigenerare

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 dello schema grezzo per gli strumenti:

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

Variabili d’ambiente

Script del pacchetto

Aggiungi i comandi del CLI come script di 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