# Riferimento CLI

## Uso di base

Esegui il comando, senza argomenti:

```bash
npx termbridge
```

Questo avvia tutto: server locale, sessione tmux e tunnel Cloudflare predefinito.

Eseguire `termbridge` senza un sottocomando equivale a `termbridge start`.

Puoi anche eseguire `termbridge start` esplicitamente con tutti i flag:

```bash
termbridge start --port 8080 --proxy 5173 --session dev --kill-on-exit --no-qr --tunnel cloudflare
```

## Flag

| Flag | Funzione | Predefinito |
|------|----------|-------------|
| `--port <port>` | Usa una porta specifica invece di una casuale | Casuale |
| `--proxy <port>` | Inoltra il traffico di un server di sviluppo locale (abilita le viste Terminal/Preview) | - |
| `--session <name>` | Assegna un nome alla sessione tmux | Generato automaticamente |
| `--kill-on-exit` | Pulisce le sessioni tmux quando Termbridge esce | Disattivato |
| `--no-qr` | Non stampa il codice QR (utile per gli script) | Disattivato |
| `--no-tunnel` | Disattiva il tunnel (richiede `--public-url`) | Disattivato |
| `--public-url <url>` | URL pubblico quando il tunnel è disattivato | - |
| `--tunnel <provider>` | Provider del tunnel (`cloudflare` o `none`) | cloudflare |
| `--tunnel-token <token>` | Usa un token Tunnel Cloudflare con nome (richiede `--port`) | - |
| `--tunnel-url <url>` | URL pubblico per il tunnel con nome (richiesto con `--tunnel-token`) | - |
| `--backend <backend>` | Backend del terminale (`tmux` o `sandbox-daytona`) | tmux |
| `--sandbox-repo <url>` | URL del repository da clonare nella sandbox Daytona | - |
| `--sandbox-branch <branch>` | Branch da estrarre nella sandbox | - |
| `--sandbox-path <path>` | Percorso del repository nella sandbox | Derivato dal nome del repository |
| `--sandbox-name <name>` | Nome della sandbox | `termbridge-<hex>` casuale |
| `--sandbox-preview-port <port>` | Porta di anteprima nella sandbox | - |
| `--sandbox-public` | Crea una sandbox pubblica | Disattivato (attivato in modalità diretta) |
| `--sandbox-direct` | Esegue il server nella sandbox Daytona (senza tunnel) | Disattivato |
| `--dev-proxy-url <url>` | Inoltra il traffico di anteprima a questo URL invece che a `localhost:<proxy port>` (usato dagli script di sviluppo) | - |
| `-h`, `--help` | Stampa il testo della guida | - |

Qualsiasi altra opzione genera un errore `unknown option: <flag>`. Non esiste un flag `--version`.

Un flag prevale sulla relativa variabile d'ambiente, con un'eccezione: al momento `TERMBRIDGE_TUNNEL` prevale su `--tunnel` e `--no-tunnel` ([#5](https://github.com/inline0/termbridge/issues/5)).

> **Nota**
> L'output `termbridge --help` integrato elenca ancora i flag `--daytona-*` e `--backend tmux | daytona`. Questi nomi vengono rifiutati; usa i flag `--sandbox-*` e `--backend sandbox-daytona` della tabella qui sopra ([#1](https://github.com/inline0/termbridge/issues/1)).

## Esempi

### Collega a una sessione tmux esistente

Se hai già una sessione tmux attiva:

```bash
termbridge --session my-session
```

### Porta fissa e sessione personalizzata

```bash
termbridge --port 8080 --session codex
```

### Uscita pulita (nessuna sessione residua)

```bash
termbridge --kill-on-exit
```

### Script (nessun output QR)

```bash
termbridge --no-qr
```

### Inoltra un server di sviluppo Vite

```bash
# Start your Vite app first
cd my-app && npm run dev  # runs on port 5173

# Then start Termbridge with proxy
termbridge --proxy 5173
```

Usa il pulsante **Viste** per passare da Terminale ad Anteprima e viceversa. L'anteprima carica l'app tramite il proxy con supporto HMR.

### Tunnel Cloudflare con nome (basato su token)

Se hai un account Cloudflare e vuoi evitare i limiti di frequenza di trycloudflare:

```bash
termbridge --port 8080 --tunnel-token <TOKEN> --tunnel-url https://term.example.com
```

### Disattiva il tunnel (usa un URL pubblico personale)

```bash
termbridge --no-tunnel --public-url https://example.com
```

## Variabili d'ambiente

Termbridge legge le variabili d'ambiente dalla shell e da un file `.env` nella directory da cui lo esegui. Le variabili già impostate nella shell hanno la precedenza su quelle del file `.env`.

### Impostazioni principali

| Variabile | Funzione |
|----------|--------------|
| `TERMBRIDGE_SESSIONS=2` | Crea più sessioni tmux all'avvio |
| `TERMBRIDGE_TMUX_CWD=/path` | Directory di lavoro per le nuove sessioni tmux |
| `TERMBRIDGE_PUBLIC_URL=https://example.com` | URL pubblico quando il tunnel è disabilitato |
| `TERMBRIDGE_TUNNEL=none` | Disabilita il tunnel |
| `TERMBRIDGE_TUNNEL_TOKEN=<token>` | Token del tunnel con nome (richiede `TERMBRIDGE_TUNNEL_URL`) |
| `TERMBRIDGE_TUNNEL_URL=https://term.example.com` | URL pubblico per il tunnel con nome |

### Avanzate

Daytona in modalità diretta imposta questi valori per il server eseguito nella sandbox. Puoi anche impostarli manualmente.

| Variabile | Funzione |
|----------|--------------|
| `TERMBRIDGE_HOST=0.0.0.0` | Indirizzo a cui si collega il server (predefinito `127.0.0.1`). L'indirizzo locale stampato URL mostra sempre `127.0.0.1`. |
| `TERMBRIDGE_COOKIE_SAMESITE=lax` | Valore `SameSite` del cookie di sessione: `lax`, `strict` o `none` (predefinito `Lax`, oppure `None` in modalità diretta) |
| `TERMBRIDGE_SHARE_FILE=/path/share-url.txt` | Scrive anche la condivisione URL in questo file |
| `TERMBRIDGE_HIDE_TERMINAL_SWITCHER=1` | Nasconde il selettore di terminale in UI |
| `TERMBRIDGE_TMUX_PATH_PREFIX=/path/bin` | Anteponi questo a `PATH` in ogni sessione tmux a cui Termbridge si avvia o si collega (inserito nella sessione come comando `export`) |

### Sviluppo

| Variabile | Funzione |
|----------|--------------|
| `TERMBRIDGE_INSECURE_COOKIE=1` | Consente i cookie HTTP (solo per lo sviluppo locale) |
| `TERMBRIDGE_PROXY_PORT=5173` | Porta proxy per lo script dev:beam:proxy |
| `TERMBRIDGE_DEV_UI=http://127.0.0.1:5000` | Sostituisce Vite dev UI URL |
| `TERMBRIDGE_DEV_PORT=3000` | Sostituisce la porta del server Termbridge in sviluppo (predefinita `8787`) |
| `TERMBRIDGE_DEV_SESSION=codex` | Nome della sessione tmux per `dev:beam` (predefinito `codex`) |
| `TERMBRIDGE_SKIP_BUILD=1` | Salta la compilazione CLI in `dev:beam` |

### Sandbox (Daytona)

| Variabile | Funzione |
|----------|--------------|
| `TERMBRIDGE_BACKEND=sandbox-daytona` | Usa il backend sandbox Daytona |
| `TERMBRIDGE_SANDBOX_DIRECT=true` | Esegue Termbridge all'interno del sandbox |
| `TERMBRIDGE_SANDBOX_SERVER_PORT=8080` | Porta del server nel sandbox |
| `TERMBRIDGE_SANDBOX_AGENTS=claude-code,codex` | Installa automaticamente e sincronizza l'autenticazione degli agenti |
| `TERMBRIDGE_SANDBOX_AGENT_ENV=...` | Variabili d'ambiente aggiuntive da inoltrare |
| `TERMBRIDGE_SANDBOX_AGENT_AUTH_PATHS=...` | File di autenticazione locali da sincronizzare |

Per la configurazione completa di Daytona, consulta la guida [Daytona](https://termbridge.inline0.dev/it/docs/sandboxes/daytona).

## Arrestare Termbridge

Premi `Ctrl+C` nel terminale in cui è in esecuzione Termbridge. Questo:

- Chiude il tunnel (se abilitato)
- Arresta il server locale
- Mantiene attive le sessioni tmux (a meno che tu non abbia usato `--kill-on-exit`)

Le sessioni tmux vengono mantenute per impostazione predefinita, così puoi riconnetterti in seguito.