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

# Kazzle CLI

> Esegui i comandi dell'app generata con il contesto di runtime di Kazzle.

# Kazzle CLI

Usa la Kazzle CLI per eseguire i comandi dell'app **in sviluppo e anteprima**:

```bash theme={"theme":"material-theme-darker"}
kazzle run -- <command>
```

Tutto dopo `--` è il comando vero. Kazzle inietta prima l'ambiente di runtime.

`kazzle run` è solo per sviluppo e anteprima. Appartiene allo script `dev`, mai a `start`. In produzione, il runtime distribuito inietta `PORT`, `HOST` e i segreti direttamente, e il comando di produzione è il comando nudo (ad es. `bun run index.ts`). La CLI `kazzle` non è installata nelle immagini distribuite, quindi un comando di produzione che chiama `kazzle run` si arresta in modo anomalo con `kazzle: command not found`.

## Cosa inietta `kazzle run`

* segreti dalla voce `env` del componente in `kazzle.config.ts`
* `PORT` e `HOST`
* URL dei componenti fratelli come `KAZZLE_APP_COMPONENT_SERVER_URL`
* identità del runtime Kazzle come ID app e nome del componente

## Esempio

```json theme={"theme":"material-theme-darker"}
{
  "scripts": {
    "dev": "kazzle run -- bun --watch server/index.ts",
    "start": "bun server/index.ts"
  }
}
```

`dev` viene eseguito tramite `kazzle run` in modo che Kazzle possa iniettare la porta di anteprima e l'env di runtime. `start` è il comando nudo — la produzione inietta `PORT`/`HOST`/segreti da sola.

Non mettere i nomi delle raccolte di segreti in `package.json`. Mettili in `kazzle.config.ts`.

```ts theme={"theme":"material-theme-darker"}
components: [
  {
    name: 'server',
    type: 'process',
    path: './server/index.ts',
    env: { collection: 'my-app', environment: 'local' },
  },
]
```

## Collegare un checkout a un'app

`kazzle run` deve sapere a quale app appartiene questa directory. Ordine di risoluzione:

1. `--app=<appId>` sulla riga di comando
2. variabile env `KAZZLE_APP_ID` (impostata automaticamente quando Kazzle avvia un componente supervisionato)
3. `.kazzle/link.json` risalito dalla directory corrente

Se nessuno di questi si risolve, `kazzle run` esce con:

```
Error: This directory is not linked to a Kazzle app. Run `kazzle link` to fix.
```

`app { create: {} }` scrive `.kazzle/link.json` automaticamente — come `.vercel/project.json` di Vercel. Il file è per-clone e gitignored. Dopo un `git clone` fresco di un'app esistente, esegui:

```bash theme={"theme":"material-theme-darker"}
kazzle link              # abbina la directory corrente ai checkout dell'app del tuo Space
kazzle link --app=<id>   # forza un'app specifica
kazzle unlink            # elimina il file di collegamento
```

L'AI può riparare un collegamento mancante da un thread con `app { link: { appId } }`.