CLI di Espobase
Lavora sui tuoi progetti dal terminale: collega una cartella a un progetto, genera tipi TypeScript, esegui query di sola lettura e controlla log e utilizzo. Richiede Node.js 20 o successivo.
Per iniziare
npx espobase login # opens your browser: sign in and click Allow npx espobase init # link this folder, write espobase.types.ts, show your app's settings
Oppure installala una volta con npm install -g espobase ed esegui espobase ….
Comandi
| espobase login | Apre il browser: accedi a Espobase e autorizza l'accesso. Sui server, usa --token espo_pat_…. |
| espobase init [<ref>] | Collega questa cartella a un progetto, scrive espobase.types.ts e mostra l'ESPOBASE_URL della tua app. |
| espobase projects list | I tuoi progetti, per organizzazione. |
| espobase projects create <name> --org <slug> | Un nuovo progetto (il suo database è pronto in un attimo). |
| espobase link <ref> / unlink | Collega questa cartella a un progetto (.espobase/project.json, puoi farne il commit senza problemi). |
| espobase gen types [--out <file>] | Tipi TypeScript per createClient<Database>() in @espobase/client. |
| espobase db query "<sql>" | SQL di sola lettura: SELECT, EXPLAIN, SHOW… |
| espobase migration new <name> | Un nuovo file SQL in espobase/migrations, con l'ora UTC attuale nel nome. |
| espobase migration list | Quali file di migrazione sono applicati, in attesa o modificati. |
| espobase db push [--dry-run] | Applica in ordine i file di migrazione in attesa, ognuno in una transazione. --dry-run li verifica e annulla tutto. |
| espobase logs [--errors] | Richieste API recenti: percorso, stato, tempi (mai corpi delle richieste o segreti). |
| espobase usage [--range 7d] | Richieste, banda, spazio database e archiviazione file, utilizzo AI. |
| espobase storage ls [<bucket>] | I tuoi bucket, o i file di uno di essi. |
| espobase deploy <cartella> --site <indirizzo> | Pubblica una cartella di build su un sito ospitato e lo rende attivo (serve il permesso Deploy dei siti). `--message`, `--no-activate`. |
| espobase sites list | I tuoi siti ospitati e i loro indirizzi. |
| espobase ai propose "<request>" | Un piano di modifica dello schema (SQL e rischio) che rivedi e applichi nella dashboard. |
| espobase open | Il progetto collegato, nella dashboard. |
| espobase whoami / logout | L'account con cui hai effettuato l'accesso; esci (e revoca l'accesso). |
Ogni comando accetta --json per gli script e --project <ref> per usare un progetto diverso da quello collegato.
Migrazioni
Tieni lo schema nel tuo repository: scrivi ogni modifica come file SQL, rivedila come il codice e inviala a un progetto dal terminale o dalla CI.
npx espobase migration new create_dishes # write the SQL in espobase/migrations/20261005143000_create_dishes.sql npx espobase db push --dry-run # runs it, then rolls everything back npx espobase db push # applies it
- I file vengono eseguiti in ordine di versione, una volta ciascuno. Espobase registra versione, nome, checksum, chi e quando; il tuo SQL resta nel tuo repository.
- Ogni file viene eseguito in una transazione insieme alla sua registrazione: viene applicato per intero o per niente. Se uno fallisce, l'invio si ferma lì e indica file e riga.
- Non modificare un file dopo averlo applicato: scrivine uno nuovo.
db pushrifiuta i file modificati e quelli più vecchi dell'ultimo applicato. - Le nuove tabelle hanno la sicurezza a livello di riga attiva. Aggiungi le loro policy nello stesso file, così la tua app può raggiungerle.
- Valgono le regole dell'editor SQL: gli sviluppatori possono modificare dati e schema; policy, GRANT e altre modifiche ai permessi richiedono un amministratore. Le istruzioni distruttive (DROP, TRUNCATE, DELETE senza WHERE…) richiedono
--allow-destructivee un amministratore. - Per inviare serve il permesso Apply migrations (database:write): viene chiesto all'accesso, oppure lo scegli quando crei un token per la CI. Nella CI aggiungi
--yes.
CI e server
Crea un token di accesso personale nella dashboard (Impostazioni account › Sviluppatore) con solo gli scope che servono al job, e passalo come ESPOBASE_TOKEN:
ESPOBASE_TOKEN=espo_pat_… npx espobase gen types --project <ref> ESPOBASE_TOKEN=espo_pat_… npx espobase db push --yes --project <ref>
Cosa la CLI può e non può fare
- Agisce come te, con il tuo ruolo, sui progetti a cui hai accesso.
- Modifica un progetto solo con permessi espliciti:
db pushapplica i tuoi file di migrazione efunctions deploypubblica le edge function edeploypubblica i siti ospitati. Il resto dell'SQL è in sola lettura, e le modifiche allo schema dell'IA sono proposte che applichi nella dashboard. - Non recupera mai password del database o chiavi API.
- L'accesso dal browser dura finché non esegui
espobase logouto lo scolleghi in Impostazioni account › Sviluppatore › App collegate. I token vengono salvati in modo che solo tu possa leggerli.