CLI Reference

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

Installazione

La CLI è inclusa nel pacchetto emdash:

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 (tutto tranne init, seed, export-seed e auth secret) 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 dev — se l’URL è localhost e nessun token è disponibile, 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 lavora con 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 formatta i risultati con consola. Quando viene reindirizzato o quando --json è impostato, restituisce JSON grezzo su stdout — adatto per jq o altri strumenti.

Comandi

emdash init

Inizializza il database con lo schema core e dati template opzionali.

npx emdash init [options]

Opzioni

Comportamento

1. Legge la configurazione emdash da package.json
2. Crea il file database se necessario
3. Esegue le migrazioni core (crea le tabelle di sistema)
4. Esegue il template schema.sql se configurato
5. Esegue il template seed.sql se configurato

emdash dev

Avvia il server di sviluppo con configurazione automatica del database.

npx emdash dev [options]

Opzioni

Esempi

# Start dev server
npx emdash dev

# Custom port
npx emdash dev --port 3000

# Generate types from remote before starting
npx emdash dev --types

Comportamento

1. Controlla ed esegue le migrazioni del database in sospeso
2. Se --types è impostato, genera i tipi TypeScript da un’istanza remota (URL da EMDASH_URL env o emdash.url in package.json)
3. Avvia il server dev 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

# 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 dei tipi TypeScript
3. Scrive i tipi nel file di output
4. Scrive schema.json a fianco come riferimento

emdash login

Accedi a un’istanza EmDash usando il flusso OAuth Device Flow.

npx emdash login [options]

Opzioni

Comportamento

1. Scopre gli endpoint di autenticazione dall’istanza
2. Se è localhost e nessuna autenticazione è configurata, usa automaticamente il bypass dev
3. Altrimenti avvia il flusso OAuth Device Flow — mostra un codice e apre il browser
4. Esegue il polling per l’autorizzazione, poi 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 salvate.

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

Gestisci 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 dimostrare che hai visto ciò che stai sovrascrivendo.

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 tra --data, --file o --stdin.

content update <collection> <id>

Come un editor di file che richiede di leggere prima di scrivere — devi fornire il token _rev da un precedente get per dimostrare che hai visto lo stato corrente. Questo previene la sovrascrittura accidentale di modifiche che non hai visto.

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

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Elimina temporaneamente 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 dal cestino.

emdash schema

Gestisci 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

Gestisci 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

emdash search

Ricerca full-text nei contenuti.

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

emdash taxonomy

Gestisci 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

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

Applica un file seed al database. Questo comando funziona direttamente su un file SQLite locale (non è necessario un server in esecuzione).

npx emdash seed [path] [options]

Argomenti

Opzioni

Risoluzione del file seed

Il comando cerca i file seed in questo ordine:

1. Argomento posizionale (se fornito)
2. .emdash/seed.json (convenzione)
3. Percorso dal campo emdash.seed di package.json

emdash export-seed

Esporta lo schema e i contenuti del database 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 del sito, tagline, link social
• Collezioni: Tutte le definizioni delle collezioni con i campi
• Tassonomie: Definizioni delle tassonomie e termini
• Menu: Menu di navigazione con le voci
• Aree widget: Aree widget e widget
• Contenuti (se richiesti): Voci con riferimenti $media e sintassi $ref: per la portabilità

emdash auth secret

Genera un secret di autenticazione sicuro per il tuo deployment.

npx emdash auth secret

Restituisce un secret casuale adatto per EMDASH_AUTH_SECRET.

File generati

.emdash/types.ts

Interfacce TypeScript generate da 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

Esportazione dello schema grezzo per gli strumenti:

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

Variabili d’ambiente

Script del pacchetto

{
	"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"
	}
}

Codici di uscita