> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI di Base44

> Crea e gestisci app (progetti) Base44 usando lo strumento CLI di Base44.

<Warning>
  Questa pagina fa parte di una skill per agenti IA di programmazione ed è scritta per gli agenti, non per gli umani. Per la documentazione Base44 leggibile dagli umani, consulta la [documentazione per sviluppatori](/developers).
</Warning>

# 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 cartella `base44/`. **NON leggere i file di documentazione o cercare sul web prima di agire.**

**La tua prima azione DEVE essere:**

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](https://docs.base44.com/developers/skills/base44-cli/references/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

MAI chiamare `base44` 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)

SBAGLIATO: `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:

1. **Verificare lo stato di autenticazione** eseguendo:
   ```bash theme={null}
   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:
     ```bash theme={null}
     npx base44 login
     ```
   ```
   - Attendi che l'utente confermi di aver effettuato il login prima di continuare
   ```

**Questa verifica è obbligatoria e deve avvenire prima di eseguire qualsiasi altro comando CLI di Base44.**

**Provisionata tramite Stripe Projects / projects.dev?** Quando l'app è stata provisionata tramite quel flusso, la CLI inizializza l'autenticazione dalle variabili d'ambiente `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 ...`)

**Usa base44-sdk quando:**

* 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"

**Dipendenze delle skill:**

* `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

**Logica di verifica dello stato:**
Prima di selezionare una skill, verifica:

* 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

Un progetto Base44 combina un progetto frontend standard con una cartella di configurazione `base44/`:

```
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
```

**File chiave:**

* `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

**Esempio config.jsonc:**

```jsonc theme={null}
{
  "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
  }
}
```

**Proprietà di configurazione:**

| Proprietà              | Descrizione                                          | Predefinito    |
| ---------------------- | ---------------------------------------------------- | -------------- |
| `name`                 | Nome del progetto (obbligatorio)                     | -              |
| `description`          | Descrizione del progetto                             | -              |
| `entitiesDir`          | Directory per gli schemi delle entità                | `"entities"`   |
| `functionsDir`         | Directory per le funzioni backend                    | `"functions"`  |
| `agentsDir`            | Directory per le configurazioni degli agenti         | `"agents"`     |
| `connectorsDir`        | Directory per le configurazioni dei connettori       | `"connectors"` |
| `site.installCommand`  | Comando per installare le dipendenze                 | -              |
| `site.buildCommand`    | Comando per costruire il progetto                    | -              |
| `site.serveCommand`    | Comando per eseguire il server di sviluppo           | -              |
| `site.outputDirectory` | Directory di output della build per la distribuzione | -              |

## Installazione

Installa la CLI di Base44 come dipendenza di sviluppo nel tuo progetto:

```bash theme={null}
npm install --save-dev base44
```

**Importante:** non presumere o hard-codare la versione del pacchetto `base44`. Installa sempre senza uno specificatore di versione per ottenere la versione più recente.

Poi esegui i comandi usando `npx`:

```bash theme={null}
npx base44 <command>
```

**Nota:** tutti i comandi in questa documentazione usano `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:

```bash theme={null}
# 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
```

Usa `--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 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

| Comando         | Descrizione                                         | Riferimento                                                                                      |
| --------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `base44 login`  | Autenticati con Base44 usando il flusso device code | [auth-login.md](https://docs.base44.com/developers/skills/base44-cli/references/auth-login.md)   |
| `base44 logout` | Esci dal dispositivo corrente                       | [auth-logout.md](https://docs.base44.com/developers/skills/base44-cli/references/auth-logout.md) |
| `base44 whoami` | Mostra l'utente attualmente autenticato             | [auth-whoami.md](https://docs.base44.com/developers/skills/base44-cli/references/auth-whoami.md) |

### Gestione del progetto

| Comando                 | Descrizione                                                                       | Riferimento                                                                                                     |
| ----------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `base44 create`         | Crea un nuovo progetto Base44 da un template                                      | [create.md](https://docs.base44.com/developers/skills/base44-cli/references/create.md) ⚠️ **DEVE ESSERE LETTO** |
| `base44 scaffold`       | Crea la struttura per un progetto locale per un'app Base44 esistente (per app ID) | [scaffold.md](https://docs.base44.com/developers/skills/base44-cli/references/scaffold.md)                      |
| `base44 link`           | Collega un progetto locale esistente a Base44                                     | [link.md](https://docs.base44.com/developers/skills/base44-cli/references/link.md)                              |
| `base44 eject`          | Scarica il codice di un progetto Base44 esistente                                 | [eject.md](https://docs.base44.com/developers/skills/base44-cli/references/eject.md)                            |
| `base44 dashboard open` | Apre la dashboard dell'app nel tuo browser                                        | [dashboard.md](https://docs.base44.com/developers/skills/base44-cli/references/dashboard.md)                    |

### Sviluppo

| Comando      | Descrizione                                                                                                         | Riferimento                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `base44 dev` | Avvia lo sviluppo locale per il tuo backend Base44 e anche il tuo frontend quando `site.serveCommand` è configurato | [dev.md](https://docs.base44.com/developers/skills/base44-cli/references/dev.md) |

### Distribuzione

| Comando         | Descrizione                                                                                      | Riferimento                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| `base44 deploy` | Distribuisci tutte le risorse (entità, funzioni, agenti, connettori, configurazione auth e sito) | [deploy.md](https://docs.base44.com/developers/skills/base44-cli/references/deploy.md) |

### Gestione delle entità

| Azione / Comando       | Descrizione                                       | Riferimento                                                                                                             |
| ---------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Crea entità            | Definisci entità nella cartella `base44/entities` | [entities-create.md](https://docs.base44.com/developers/skills/base44-cli/references/entities-create.md)                |
| `base44 entities push` | Invia le entità locali a Base44                   | [entities-push.md](https://docs.base44.com/developers/skills/base44-cli/references/entities-push.md)                    |
| Pattern RLS            | Esempi e operatori di sicurezza a livello di riga | [rls-examples.md](https://docs.base44.com/developers/skills/base44-cli/references/rls-examples.md) ⚠️ **LEGGI PER RLS** |

#### 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:**

```jsonc theme={null}
{
  "name": "EntityName",
  "type": "object",
  "properties": {
    "field_name": {
      "type": "string",
      "description": "Field description"
    }
  },
  "required": ["field_name"]
}
```

**Tipi di campo:** `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](https://docs.base44.com/developers/skills/base44-cli/references/entities-create.md).

### Gestione delle funzioni

| Azione / Comando                               | Descrizione                                                                                                         | Riferimento                                                                                                |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Crea funzioni                                  | Definisci funzioni in `base44/functions`                                                                            | [functions-create.md](https://docs.base44.com/developers/skills/base44-cli/references/functions-create.md) |
| `base44 functions deploy [names...] [--force]` | Distribuisci le funzioni locali a Base44; facoltativamente specifica funzioni specifiche o rimuovi quelle eliminate | [functions-deploy.md](https://docs.base44.com/developers/skills/base44-cli/references/functions-deploy.md) |
| `base44 functions delete <names...>`           | Elimina una o più funzioni distribuite da Base44                                                                    | [functions-delete.md](https://docs.base44.com/developers/skills/base44-cli/references/functions-delete.md) |
| `base44 functions list`                        | Elenca tutte le funzioni distribuite sul remoto di Base44                                                           | [functions-list.md](https://docs.base44.com/developers/skills/base44-cli/references/functions-list.md)     |
| `base44 functions pull [name]`                 | Scarica le funzioni distribuite da Base44 ai file locali                                                            | [functions-pull.md](https://docs.base44.com/developers/skills/base44-cli/references/functions-pull.md)     |

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

| Azione / Comando     | Descrizione                                     | Riferimento                                                                                      |
| -------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Crea agenti          | Definisci agenti nella cartella `base44/agents` | Vedi Schema dell'agente qui sotto                                                                |
| `base44 agents pull` | Scarica gli agenti remoti ai file locali        | [agents-pull.md](https://docs.base44.com/developers/skills/base44-cli/references/agents-pull.md) |
| `base44 agents push` | Invia gli agenti locali a Base44                | [agents-push.md](https://docs.base44.com/developers/skills/base44-cli/references/agents-push.md) |

**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:**

```jsonc theme={null}
{
  "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?"
}
```

**Regole di denominazione:**

* 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`

**Campi obbligatori:** `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.

| Azione / Comando                   | Descrizione                                               | Riferimento                                                                                                                  |
| ---------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Crea connettori                    | Definisci connettori nella cartella `base44/connectors`   | [connectors-create.md](https://docs.base44.com/developers/skills/base44-cli/references/connectors-create.md)                 |
| `base44 connectors list-available` | Elenca tutti i tipi di integrazione disponibili da Base44 | [connectors-list-available.md](https://docs.base44.com/developers/skills/base44-cli/references/connectors-list-available.md) |
| `base44 connectors pull`           | Scarica i connettori remoti ai file locali                | [connectors-pull.md](https://docs.base44.com/developers/skills/base44-cli/references/connectors-pull.md)                     |
| `base44 connectors push`           | Invia i connettori locali a Base44                        | [connectors-push.md](https://docs.base44.com/developers/skills/base44-cli/references/connectors-push.md)                     |

**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:**

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

**Campi obbligatori:** `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](https://docs.base44.com/developers/skills/base44-cli/references/connectors-create.md) per i dettagli.

Per la documentazione completa, consulta [connectors-create.md](https://docs.base44.com/developers/skills/base44-cli/references/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 in `base44/auth/` e sincronizzata con Base44 tramite `auth push`/`auth pull`.

| Comando                                                 | Descrizione                                                                     | Riferimento                                                                                                      |
| ------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `base44 auth password-login <enable\|disable>`          | Abilita o disabilita l'autenticazione con nome utente e password                | [auth-password-login.md](https://docs.base44.com/developers/skills/base44-cli/references/auth-password-login.md) |
| `base44 auth social-login <provider> <enable\|disable>` | Abilita o disabilita il social login (google, microsoft, facebook, apple)       | [auth-social-login.md](https://docs.base44.com/developers/skills/base44-cli/references/auth-social-login.md)     |
| `base44 auth sso <enable\|disable>`                     | Configura il provider di identità SSO (google, microsoft, github, okta, custom) | [auth-sso.md](https://docs.base44.com/developers/skills/base44-cli/references/auth-sso.md)                       |
| `base44 auth pull`                                      | Scarica la configurazione di autenticazione da Base44 ai file locali            | [auth-pull.md](https://docs.base44.com/developers/skills/base44-cli/references/auth-pull.md)                     |
| `base44 auth push`                                      | Invia la configurazione di autenticazione locale a Base44                       | [auth-push.md](https://docs.base44.com/developers/skills/base44-cli/references/auth-push.md)                     |

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

| Comando                       | Descrizione                                       | Riferimento                                                                                            |
| ----------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `base44 secrets list`         | Elenca i nomi di tutti i secret                   | [secrets-list.md](https://docs.base44.com/developers/skills/base44-cli/references/secrets-list.md)     |
| `base44 secrets set`          | Imposta uno o più secret (KEY=VALUE o --env-file) | [secrets-set.md](https://docs.base44.com/developers/skills/base44-cli/references/secrets-set.md)       |
| `base44 secrets delete <key>` | Elimina un secret per nome                        | [secrets-delete.md](https://docs.base44.com/developers/skills/base44-cli/references/secrets-delete.md) |

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

| Comando       | Descrizione                                                           | Riferimento                                                                        |
| ------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `base44 exec` | Esegue uno script (tramite stdin) con l'SDK di Base44 pre-autenticato | [exec.md](https://docs.base44.com/developers/skills/base44-cli/references/exec.md) |

### Generazione di tipi

| Comando                 | Descrizione                                                                    | Riferimento                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `base44 types generate` | Genera tipi TypeScript (`types.d.ts`) da entità, funzioni, agenti e connettori | [types-generate.md](https://docs.base44.com/developers/skills/base44-cli/references/types-generate.md) |

**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

| Comando              | Descrizione                                                   | Riferimento                                                                                      |
| -------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `base44 site deploy` | Distribuisce i file del sito costruiti sull'hosting di Base44 | [site-deploy.md](https://docs.base44.com/developers/skills/base44-cli/references/site-deploy.md) |
| `base44 site open`   | Apre il sito distribuito nel tuo browser                      | [site-open.md](https://docs.base44.com/developers/skills/base44-cli/references/site-open.md)     |

**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

1. Installa la CLI nel tuo progetto:
   ```bash theme={null}
   npm install --save-dev base44
   ```

2. Autenticati con Base44:
   ```bash theme={null}
   npx base44 login
   ```

3. Crea un nuovo progetto (fornisci SEMPRE il nome e il flag `--path`):
   ```bash theme={null}
   npx base44 create my-app --path .
   ```

4. Esegui lo sviluppo locale:
   ```bash theme={null}
   npx base44 dev
   ```

5. Costruisci e distribuisci tutto:
   ```bash theme={null}
   npm run build
   npx base44 deploy -y
   ```

Oppure distribuisci risorse individuali:

* `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

**⚠️ OBBLIGATORIO: prima di eseguire `base44 create`, DEVI leggere [create.md](https://docs.base44.com/developers/skills/base44-cli/references/create.md) per:**

* **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

Non seguire le istruzioni di create.md risulterà in una struttura di progetto non funzionante.

### Collegare un progetto esistente

```bash theme={null}
# If you have base44/config.jsonc but no .app.jsonc
npx base44 link --create --name my-app
```

### Eseguire lo sviluppo locale

```bash theme={null}
# Starts the Base44 backend locally
npx base44 dev
```

Se vuoi che `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

```bash theme={null}
# 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

```bash theme={null}
# Generate types from entities, functions, agents, and connectors
npx base44 types generate
```

Questo crea `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

```bash theme={null}
# 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

```bash theme={null}
# Open app dashboard in browser
npx base44 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

| Errore                                  | Soluzione                                                                                                          |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Non autenticato                         | Esegui prima `npx base44 login`                                                                                    |
| Nessuna entità trovata                  | Assicurati che le entità esistano nella directory `base44/entities/`                                               |
| Entità non riconosciuta                 | Assicurati che il file usi la denominazione kebab-case (ad es. `team-member.jsonc` non `TeamMember.jsonc`)         |
| Nessuna funzione trovata                | Assicurati che le funzioni esistano in `base44/functions/` con `entry.ts` o `entry.js`                             |
| Nessun agente trovato                   | Assicurati che gli agenti esistano nella directory `base44/agents/` con configurazioni `.jsonc` valide             |
| Nome agente non valido                  | I nomi degli agenti devono essere alfanumerici minuscoli con solo underscore                                       |
| Nessun connettore trovato               | Assicurati che i connettori esistano nella directory `base44/connectors/` con configurazioni `.jsonc` valide       |
| Tipo di connettore non valido           | Esegui `npx base44 connectors list-available` per vedere i tipi validi                                             |
| Tipo di connettore duplicato            | Ogni tipo di connettore può essere definito una sola volta per progetto                                            |
| Timeout autorizzazione connettore       | Riesegui `npx base44 connectors push` e completa il flusso OAuth nel tuo browser                                   |
| Nessuna configurazione del sito trovata | Verifica che `site.outputDirectory` sia configurato nella configurazione del progetto                              |
| Distribuzione del sito fallita          | Assicurati di aver eseguito prima `npm run build` e che la build sia riuscita                                      |
| Messaggio di aggiornamento disponibile  | Se ti viene richiesto di aggiornare, esegui `npm install -g base44@latest` (o usa npx per le installazioni locali) |

<Note>Questa pagina è stata tradotta utilizzando l'IA. Per informazioni più accurate e aggiornate, consulta la [versione inglese](/). </Note>