CLI di Base44
Crea e gestisci app (progetti) Base44 usando lo strumento CLI di Base44.⚡ AZIONE IMMEDIATA RICHIESTA - Leggi prima questo
Questa skill si attiva a QUALSIASI menzione di “base44” o quando esiste una cartellabase44/. NON leggere i file di documentazione o cercare sul web prima di agire.
La tua prima azione DEVE essere:
- Verificare se
base44/config.jsoncesiste nella directory corrente - Se SÌ (scenario di progetto esistente):
- Trasferisci alla skill base44-sdk per l’implementazione
- Questa skill gestisce solo i comandi CLI (login, deploy, entities push)
- Se NO, decidi tra due percorsi di inizializzazione:
- App provisionata — l’app Base44 esiste già perché è stata appena provisionata tramite un flusso Stripe Projects / projects.dev, OPPURE
BASE44_APP_ID(oBASE44_PROJECTS_BASE44_APP_ID) è presente nell’ambiente o in un file.env/.env.local:- Esegui
npx base44 scaffoldper configurare i file locali per quell’app esistente - NON eseguire
npx base44 create— quello crea una seconda app duplicata. Consulta scaffold.md.
- Esegui
- Nuovo progetto — nessuna app esiste ancora e nessuna è stata provisionata:
- Questa skill (base44-cli) gestisce la richiesta; guida l’utente attraverso
npx base44 create - NON attivare ancora base44-sdk
- Questa skill (base44-cli) gestisce la richiesta; guida l’utente attraverso
- App provisionata — l’app Base44 esiste già perché è stata appena provisionata tramite un flusso Stripe Projects / projects.dev, OPPURE
Critico: solo installazione locale
MAI chiamarebase44 direttamente. La CLI è installata localmente come dipendenza di sviluppo e deve essere accessibile tramite un package manager:
npx base44 <command>(npm - consigliato)yarn base44 <command>(yarn)pnpm base44 <command>(pnpm)
base44 login
CORRETTO: npx base44 login
OBBLIGATORIO: verifica dell’autenticazione all’inizio della sessione
CRITICO: proprio all’inizio di ogni sessione IA quando questa skill è attivata, DEVI:-
Verificare lo stato di autenticazione eseguendo:
-
Se l’utente è loggato (il comando ha successo e mostra un’email):
- Continua con l’attività richiesta
-
Se l’utente NON è loggato (il comando fallisce o mostra un errore):
- FERMATI immediatamente
- NON procedere con nessuna operazione CLI
- Chiedi all’utente di effettuare il login manualmente eseguendo:
BASE44_ACCESS_TOKEN / BASE44_REFRESH_TOKEN che inietta (i nomi con prefisso BASE44_PROJECTS_* sono normalizzati automaticamente). In tal caso npx base44 whoami ha già successo e non hai bisogno di un npx base44 login interattivo.
Panoramica
La CLI di Base44 fornisce strumenti da riga di comando per l’autenticazione, la creazione di progetti, la gestione delle entità e la distribuzione di applicazioni Base44. È indipendente dal framework e funziona con framework frontend popolari come Vite, Next.js e Create React App, Svelte, Vue e altri.Quando usare questa skill vs base44-sdk
Usa base44-cli quando:- Creare un progetto Base44 NUOVO da zero
- Inizializzare un progetto in una directory vuota
- Configurare file locali per un’app esistente provisionata esternamente (ad es. tramite un flusso Stripe Projects / projects.dev) → usa
scaffold - La directory manca di
base44/config.jsonc - L’utente menziona: “crea un nuovo progetto”, “inizializza il progetto”, “configura un progetto”, “avvia una nuova app Base44”
- Distribuire, fare push delle entità o autenticarsi tramite CLI
- Lavorare con comandi CLI (
npx base44 ...)
- Costruire funzionalità in un progetto Base44 ESISTENTE
base44/config.jsoncesiste già- Scrivere codice JavaScript/TypeScript usando l’SDK di Base44
- Implementare funzionalità, componenti o feature
- L’utente menziona: “implementa”, “costruisci una funzionalità”, “aggiungi funzionalità”, “scrivi codice”
base44-cliè un prerequisito perbase44-sdknei nuovi progetti- Se l’utente vuole “creare un’app” e nessun progetto Base44 esiste, usa prima
base44-cli base44-sdkpresume che un progetto Base44 sia già inizializzato
- SE (l’utente menziona “crea/costruisci app” O “crea un progetto”):
- SE (
base44/config.jsoncesiste): → Usa base44-sdk (il progetto esiste, costruisci funzionalità) - ALTRIMENTI SE (l’app è stata provisionata esternamente —
BASE44_APP_ID/BASE44_PROJECTS_BASE44_APP_IDimpostato, o un flusso Stripe Projects / projects.dev è appena stato eseguito): → Usa base44-cli →npx base44 scaffold(configura i file locali per l’app esistente; NON eseguirecreate) - ALTRIMENTI:
→ Usa base44-cli →
npx base44 create(è necessaria l’inizializzazione di un nuovo progetto)
- SE (
Struttura del progetto
Un progetto Base44 combina un progetto frontend standard con una cartella di configurazionebase44/:
base44/config.jsonc- nome del progetto, descrizione, impostazioni di build del sitobase44/entities/*.jsonc- schemi del modello dati (vedi la sezione Schema dell’entità)base44/functions/*/entry.ts- punto di ingresso della funzione backendbase44/agents/*.jsonc- configurazioni degli agenti (facoltativo)base44/.types/types.d.ts- tipi TypeScript auto-generati per entità, funzioni e agenti (creati danpx base44 types generate)base44/connectors/*.jsonc- configurazioni dei connettori OAuth (facoltativo)src/api/base44Client.js- client SDK pre-configurato per uso frontend
Installazione
Installa la CLI di Base44 come dipendenza di sviluppo nel tuo progetto:base44. Installa sempre senza uno specificatore di versione per ottenere la versione più recente.
Poi esegui i comandi usando npx:
npx base44. Puoi anche usare yarn base44 o pnpm base44 se preferisci.
Opzione globale --app-id
La CLI ha un’opzione globale --app-id <id> per i comandi che necessitano solo di un contesto app, non di file locali del progetto.
Ordine di risoluzione: flag --app-id → variabile d’ambiente BASE44_APP_ID → base44/.app.jsonc locale
Questo è utile quando vuoi ispezionare o operare su un’app senza passare in una directory di progetto collegata. Esempi comuni:
--app-id per comandi con scope app come exec e logs.
Non usare --app-id per comandi che necessitano di file locali del progetto:
base44 createcrea una nuova app, quindi rifiuta--app-idbase44 devviene eseguito da un progetto locale collegato, quindi rifiuta--app-idbase44 deployrichiede ancora una directory di progetto locale perché legge risorse locali
Comandi disponibili
Autenticazione
Gestione del progetto
Sviluppo
Distribuzione
Gestione delle entità
Schema dell’entità (riferimento rapido)
Segui SEMPRE questa struttura esatta quando crei file di entità: Denominazione dei file:base44/entities/{kebab-case-name}.jsonc (ad es. team-member.jsonc per TeamMember)
Template dello schema:
string, number, integer, boolean, array, object, binary
Formati stringa: date, date-time, time, email, uri, hostname, ipv4, ipv6, uuid, file, regex, richtext
Per gli enum: aggiungi "enum": ["value1", "value2"] e facoltativamente "default": "value1"
Nomi delle entità: devono essere solo alfanumerici (pattern: /^[a-zA-Z0-9]+$/)
Per la documentazione completa, consulta entities-create.md.
Gestione delle funzioni
Gestione degli agenti
Gli agenti sono assistenti IA conversazionali che possono interagire con gli utenti, accedere alle entità della tua app e chiamare funzioni backend. Usa questi comandi per gestire le configurazioni degli agenti.
Nota: i comandi degli agenti eseguono una sincronizzazione completa: fare il push sostituisce tutti gli agenti remoti con quelli locali, e fare il pull sostituisce tutti gli agenti locali con quelli remoti.
Schema dell’agente (riferimento rapido)
Denominazione dei file:base44/agents/{agent_name}.jsonc (ad es. support_agent.jsonc)
Template dello schema:
- I nomi degli agenti devono corrispondere al pattern:
/^[a-z0-9_]+$/(alfanumerico minuscolo con underscore, 1-100 caratteri) - Validi:
support_agent,order_bot - Non validi:
Support-Agent,OrderBot
name, description, instructions
Campi facoltativi: tool_configs (predefinito []), whatsapp_greeting
Tipi di tool config:
- Tool di entità:
entity_name+allowed_operations(array di:read,create,update,delete) - Tool di funzione backend:
function_name+description
Gestione dei connettori
I connettori permettono alla tua app di connettersi a servizi esterni (Google Calendar, Slack, Stripe, ecc.). La maggior parte dei connettori usa OAuth per fornire token di accesso per le funzioni backend che chiamano API esterne. Stripe è l’eccezione — viene provisionato automaticamente lato server senza flusso OAuth nel browser.
Nota: i comandi dei connettori eseguono una sincronizzazione completa: fare il push sostituisce tutti i connettori remoti con quelli locali (e attiva OAuth per i nuovi connettori OAuth), e fare il pull sostituisce tutti i connettori locali con quelli remoti.
Schema del connettore (riferimento rapido)
Denominazione dei file:base44/connectors/{type}.jsonc (ad es. googlecalendar.jsonc, slack.jsonc)
Template dello schema:
type
Campi facoltativi: scopes (predefinito [])
Tipi di connettore disponibili: esegui npx base44 connectors list-available per vedere tutti i tipi di integrazione supportati.
Nota: stripe è anche un tipo di connettore valido ma non viene restituito da list-available. Trattalo come un tipo supportato — viene provisionato automaticamente da Base44 senza flusso OAuth nel browser. Consulta connectors-create.md per i dettagli.
Per la documentazione completa, consulta connectors-create.md.
Configurazione dell’autenticazione
Gestisci le impostazioni di autenticazione della tua app (ad es. login con nome utente e password). La configurazione di autenticazione è memorizzata inbase44/auth/ e sincronizzata con Base44 tramite auth push/auth pull.
Nota: la configurazione di autenticazione viene anche distribuita come parte di
base44 deploy.
Gestione dei secret
Gestisci i secret del progetto (variabili d’ambiente memorizzate in modo sicuro in Base44). Questi comandi sono nascosti dall’output di--help ma sono completamente funzionali.
Esecuzione di script
Esegui script una tantum contro la tua app con l’SDK di Base44 pre-autenticato. Usalo per eseguire operazioni CRUD sulle entità (base44.entities.MyEntity.list/create/update/delete), chiamare funzioni backend (base44.functions.invoke("myFunction", args)), invocare agenti o accedere a qualsiasi altra risorsa esposta dall’SDK — senza distribuire una funzione completa. Utile per migrazioni di dati, operazioni multiple, debugging e flussi di lavoro scriptati.
Generazione di tipi
Output:
base44/.types/types.d.ts — arricchisce il modulo @base44/sdk con registri tipizzati (EntityTypeRegistry, FunctionNameRegistry, AgentNameRegistry, ConnectorTypeRegistry).
Nessuna autenticazione richiesta. Viene eseguito interamente in locale. Aggiorna automaticamente tsconfig.json per includere i tipi generati.
Gestione del sito
Solo SPA: l’hosting di Base44 supporta applicazioni Single Page con un unico punto di ingresso
index.html. Tutte le route sono servite da index.html (routing lato client).
Avvio rapido
-
Installa la CLI nel tuo progetto:
-
Autenticati con Base44:
-
Crea un nuovo progetto (fornisci SEMPRE il nome e il flag
--path): -
Esegui lo sviluppo locale:
-
Costruisci e distribuisci tutto:
npx base44 entities push- invia solo le entitànpx base44 functions deploy- distribuisce solo le funzioninpx base44 functions delete <name>- elimina una funzione distribuitanpx base44 functions list- elenca tutte le funzioni distribuitenpx base44 functions pull- scarica le funzioni distribuite ai file localinpx base44 agents push- invia solo gli agentinpx base44 connectors pull- scarica i connettori da Base44npx base44 connectors push- invia solo i connettorinpx base44 auth pull- scarica la configurazione auth da Base44npx base44 auth push- invia solo la configurazione authnpx base44 site deploy -y- distribuisce solo il sito
Flussi di lavoro comuni
Creare un nuovo progetto
⚠️ OBBLIGATORIO: prima di eseguirebase44 create, DEVI leggere create.md per:
- Selezione del template - scegli il template corretto (
backend-and-clientvsbackend-only) - Flusso corretto - template diversi richiedono passaggi di configurazione diversi
- Insidie comuni - evita errori di creazione di cartelle che causano fallimenti
Collegare un progetto esistente
Eseguire lo sviluppo locale
base44 dev esegua anche il tuo frontend, verifica che base44/config.jsonc abbia site.serveCommand impostato correttamente (ad esempio, "serveCommand": "npm run dev"). Quando quel campo è presente, base44 dev esegue insieme sia il backend sia il frontend.
Distribuire tutte le modifiche
Generare tipi TypeScript
base44/.types/types.d.ts con registri tipizzati per il modulo @base44/sdk. Esegui questo dopo aver modificato entità, funzioni, agenti o connettori per mantenere i tipi sincronizzati. Nessuna autenticazione richiesta.
Distribuire risorse individuali
Aprire la dashboard
Autenticazione
La maggior parte dei comandi richiede l’autenticazione. Se non sei loggato, la CLI ti chiederà automaticamente di effettuare il login. La tua sessione è memorizzata in locale e persiste tra le sessioni della CLI.Risoluzione dei problemi
Questa pagina è stata tradotta utilizzando l’IA. Per informazioni più accurate e aggiornate, consulta la versione inglese.