​

CLI di Base44

​

⚡ AZIONE IMMEDIATA RICHIESTA - Leggi prima questo

1. Verificare se base44/config.jsonc esiste nella directory corrente
2. 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)
3. 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 (o BASE44_PROJECTS_BASE44_APP_ID) è presente nell’ambiente o in un file .env/.env.local:
     • Esegui npx base44 scaffold per configurare i file locali per quell’app esistente
     • NON eseguire npx base44 create — quello crea una seconda app duplicata. Consulta scaffold.md.
   • 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

​

Critico: solo installazione locale

• npx base44 <command> (npm - consigliato)
• yarn base44 <command> (yarn)
• pnpm base44 <command> (pnpm)

​

OBBLIGATORIO: verifica dell’autenticazione all’inizio della sessione

1. Verificare lo stato di autenticazione eseguendo:
   npx base44 whoami
   
2. Se l’utente è loggato (il comando ha successo e mostra un’email):
   • Continua con l’attività richiesta
3. 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:
     npx base44 login
     
   - Attendi che l'utente confermi di aver effettuato il login prima di continuare
   

​

Panoramica

​

Quando usare questa skill vs base44-sdk

• 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.jsonc esiste 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 per base44-sdk nei nuovi progetti
• Se l’utente vuole “creare un’app” e nessun progetto Base44 esiste, usa prima base44-cli
• base44-sdk presume che un progetto Base44 sia già inizializzato

• SE (l’utente menziona “crea/costruisci app” O “crea un progetto”):
  • SE (base44/config.jsonc esiste): → Usa base44-sdk (il progetto esiste, costruisci funzionalità)
  • ALTRIMENTI SE (l’app è stata provisionata esternamente — BASE44_APP_ID/BASE44_PROJECTS_BASE44_APP_ID impostato, 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 eseguire create)
  • ALTRIMENTI: → Usa base44-cli → npx base44 create (è necessaria l’inizializzazione di un nuovo progetto)

​

Struttura del progetto

my-app/
├── base44/                      # Base44 configuration (created by CLI)
│   ├── config.jsonc             # Project settings, site config
│   ├── .types/                  # Auto-generated TypeScript types (created by `types generate`)
│   │   └── types.d.ts           # Module augmentation for @base44/sdk
│   ├── entities/                # Entity schema definitions
│   │   ├── task.jsonc
│   │   └── board.jsonc
│   ├── functions/               # Backend functions (optional)
│   │   └── my-function/
│   │       └── entry.ts
│   ├── agents/                  # Agent configurations (optional)
│   │   └── support_agent.jsonc
│   └── connectors/              # OAuth connector configurations (optional)
│       └── googlecalendar.jsonc
├── src/                         # Frontend source code
│   ├── api/
│   │   └── base44Client.js      # Base44 SDK client
│   ├── pages/
│   ├── components/
│   └── main.jsx
├── index.html                   # SPA entry point
├── package.json
└── vite.config.js               # Or your framework's config

• base44/config.jsonc - nome del progetto, descrizione, impostazioni di build del sito
• base44/entities/*.jsonc - schemi del modello dati (vedi la sezione Schema dell’entità)
• base44/functions/*/entry.ts - punto di ingresso della funzione backend
• base44/agents/*.jsonc - configurazioni degli agenti (facoltativo)
• base44/.types/types.d.ts - tipi TypeScript auto-generati per entità, funzioni e agenti (creati da npx base44 types generate)
• base44/connectors/*.jsonc - configurazioni dei connettori OAuth (facoltativo)
• src/api/base44Client.js - client SDK pre-configurato per uso frontend

{
  "name": "My App",                    // Required: project name
  "description": "App description",    // Optional: project description
  "entitiesDir": "./entities",         // Optional: default "entities"
  "functionsDir": "./functions",       // Optional: default "functions"
  "agentsDir": "./agents",             // Optional: default "agents"
  "connectorsDir": "./connectors",     // Optional: default "connectors"
  "site": {                            // Optional: site deployment config
    "installCommand": "npm install",   // Optional: install dependencies
    "buildCommand": "npm run build",   // Optional: build command
    "serveCommand": "npm run dev",     // Optional: local dev server
    "outputDirectory": "./dist"        // Optional: build output directory
  }
}

​

Installazione

npm install --save-dev base44

npx base44 <command>

​

Opzione globale --app-id

# Run a one-off script against a specific app
cat ./script.ts | npx base44 exec --app-id app_123

# Fetch logs for a deployed app without a local checkout
npx base44 logs --app-id app_123 --level error

• base44 create crea una nuova app, quindi rifiuta --app-id
• base44 dev viene eseguito da un progetto locale collegato, quindi rifiuta --app-id
• base44 deploy richiede 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)

{
  "name": "EntityName",
  "type": "object",
  "properties": {
    "field_name": {
      "type": "string",
      "description": "Field description"
    }
  },
  "required": ["field_name"]
}

​

Gestione delle funzioni

​

Gestione degli agenti

​

Schema dell’agente (riferimento rapido)

{
  "name": "agent_name",
  "description": "Brief description of what this agent does",
  "instructions": "Detailed instructions for the agent's behavior",
  "tool_configs": [
    // Entity tool - gives agent access to entity operations
    { "entity_name": "tasks", "allowed_operations": ["read", "create", "update", "delete"] },
    // Backend function tool - gives agent access to a function
    { "function_name": "send_email", "description": "Send an email notification" }
  ],
  "whatsapp_greeting": "Hello! How can I help you today?"
}

• 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

• Tool di entità: entity_name + allowed_operations (array di: read, create, update, delete)
• Tool di funzione backend: function_name + description

​

Gestione dei connettori

​

Schema del connettore (riferimento rapido)

{
  "type": "googlecalendar",
  "scopes": [
    "https://www.googleapis.com/auth/calendar.readonly",
    "https://www.googleapis.com/auth/calendar.events"
  ]
}

​

Configurazione dell’autenticazione

​

Gestione dei secret

​

Esecuzione di script

​

Generazione di tipi

​

Gestione del sito

​

Avvio rapido

1. Installa la CLI nel tuo progetto:
   npm install --save-dev base44
   
2. Autenticati con Base44:
   npx base44 login
   
3. Crea un nuovo progetto (fornisci SEMPRE il nome e il flag --path):
   npx base44 create my-app --path .
   
4. Esegui lo sviluppo locale:
   npx base44 dev
   
5. Costruisci e distribuisci tutto:
   npm run build
   npx base44 deploy -y
   

• npx base44 entities push - invia solo le entità
• npx base44 functions deploy - distribuisce solo le funzioni
• npx base44 functions delete <name> - elimina una funzione distribuita
• npx base44 functions list - elenca tutte le funzioni distribuite
• npx base44 functions pull - scarica le funzioni distribuite ai file locali
• npx base44 agents push - invia solo gli agenti
• npx base44 connectors pull - scarica i connettori da Base44
• npx base44 connectors push - invia solo i connettori
• npx base44 auth pull - scarica la configurazione auth da Base44
• npx base44 auth push - invia solo la configurazione auth
• npx base44 site deploy -y - distribuisce solo il sito

​

Flussi di lavoro comuni

​

Creare un nuovo progetto

• Selezione del template - scegli il template corretto (backend-and-client vs backend-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

# If you have base44/config.jsonc but no .app.jsonc
npx base44 link --create --name my-app

​

Eseguire lo sviluppo locale

# Starts the Base44 backend locally
npx base44 dev

​

Distribuire tutte le modifiche

# Generate types (optional, for TypeScript projects)
npx base44 types generate

# Build your project first
npm run build

# Deploy everything (entities, functions, and site)
npx base44 deploy -y

​

Generare tipi TypeScript

# Generate types from entities, functions, agents, and connectors
npx base44 types generate

​

Distribuire risorse individuali

# Push only entities
npx base44 entities push

# Deploy only functions (all)
npx base44 functions deploy
# Deploy specific functions
npx base44 functions deploy my-function other-function
# Deploy and prune removed functions
npx base44 functions deploy --force

# Push only agents
npx base44 agents push

# Pull connectors from Base44
npx base44 connectors pull

# Push only connectors
npx base44 connectors push

# Deploy only site
npx base44 site deploy -y

​

Aprire la dashboard

# Open app dashboard in browser
npx base44 dashboard

​

Autenticazione

​

Risoluzione dei problemi