# Referencia de CLI

## Uso básico

Ejecute el comando sin argumentos:

```bash
npx termbridge
```

Esto lo inicia todo: el servidor local, la sesión tmux y el túnel Cloudflare predeterminado.

Ejecutar `termbridge` sin un subcomando equivale a `termbridge start`.

También puede ejecutar `termbridge start` explícitamente con todos los parámetros:

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

## Parámetros

| Parámetro | Función | Valor predeterminado |
|------|--------------|---------|
| `--port <port>` | Usar un puerto específico en lugar de uno aleatorio | Aleatorio |
| `--proxy <port>` | Aplicar proxy a un servidor de desarrollo local (habilita las vistas Terminal/Preview) | - |
| `--session <name>` | Nombrar la sesión tmux | Generado automáticamente |
| `--kill-on-exit` | Limpiar las sesiones tmux cuando se cierre Termbridge | Desactivado |
| `--no-qr` | No imprimir el código QR (útil para scripts) | Desactivado |
| `--no-tunnel` | Deshabilitar el túnel (requiere `--public-url`) | Desactivado |
| `--public-url <url>` | URL público cuando el túnel está deshabilitado | - |
| `--tunnel <provider>` | Proveedor del túnel (`cloudflare` o `none`) | cloudflare |
| `--tunnel-token <token>` | Usar un token de túnel Cloudflare con nombre (requiere `--port`) | - |
| `--tunnel-url <url>` | URL público para el túnel con nombre (obligatorio con `--tunnel-token`) | - |
| `--backend <backend>` | Backend de terminal (`tmux` o `sandbox-daytona`) | tmux |
| `--sandbox-repo <url>` | URL del repositorio que se clonará en el entorno aislado Daytona | - |
| `--sandbox-branch <branch>` | Rama que se extraerá en el entorno aislado | - |
| `--sandbox-path <path>` | Ruta del repositorio en el entorno aislado | Derivada del nombre del repositorio |
| `--sandbox-name <name>` | Nombre del entorno aislado | `termbridge-<hex>` aleatorio |
| `--sandbox-preview-port <port>` | Puerto de vista previa en el entorno aislado | - |
| `--sandbox-public` | Crear un entorno aislado público | Desactivado (activado en modo directo) |
| `--sandbox-direct` | Ejecutar el servidor dentro del entorno aislado Daytona (sin túnel) | Desactivado |
| `--dev-proxy-url <url>` | Redirigir el tráfico de vista previa a este URL en lugar de a `localhost:<proxy port>` (usado por los scripts de desarrollo) | - |
| `-h`, `--help` | Imprimir el texto de ayuda | - |

Cualquier otra opción produce un error con `unknown option: <flag>`. No existe un parámetro `--version`.

Un parámetro prevalece sobre su variable de entorno, con una excepción: actualmente `TERMBRIDGE_TUNNEL` prevalece sobre `--tunnel` y `--no-tunnel` ([#5](https://github.com/inline0/termbridge/issues/5)).

> **Nota**
> La salida integrada de `termbridge --help` sigue mostrando los parámetros `--daytona-*` y `--backend tmux | daytona`. Se rechazan esos nombres; use los parámetros `--sandbox-*` y `--backend sandbox-daytona` de la tabla anterior ([#1](https://github.com/inline0/termbridge/issues/1)).

## Ejemplos

### Conectarse a una sesión tmux existente

Si ya tiene una sesión tmux en ejecución:

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

### Puerto fijo y sesión personalizada

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

### Cierre limpio (sin sesiones residuales)

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

### Uso en scripts (sin salida QR)

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

### Aplicar proxy a un servidor de desarrollo 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
```

Use el botón **Views** para alternar entre Terminal y Preview. Preview carga su aplicación a través del proxy con compatibilidad con HMR.

### Túnel Cloudflare con nombre (basado en token)

Si tiene una cuenta de Cloudflare y quiere evitar los límites de frecuencia de trycloudflare:

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

### Deshabilitar el túnel (use su propio URL público)

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

## Variables de entorno

Termbridge lee las variables de entorno del shell y de un archivo `.env` del directorio desde el que se ejecuta. Las variables ya definidas en el shell tienen prioridad sobre las del archivo `.env`.

### Ajustes principales

| Variable | Función |
|----------|--------------|
| `TERMBRIDGE_SESSIONS=2` | Crear varias sesiones tmux al iniciar |
| `TERMBRIDGE_TMUX_CWD=/path` | Directorio de trabajo para las nuevas sesiones tmux |
| `TERMBRIDGE_PUBLIC_URL=https://example.com` | URL público cuando el túnel está deshabilitado |
| `TERMBRIDGE_TUNNEL=none` | Deshabilitar el túnel |
| `TERMBRIDGE_TUNNEL_TOKEN=<token>` | Token del túnel con nombre (requiere `TERMBRIDGE_TUNNEL_URL`) |
| `TERMBRIDGE_TUNNEL_URL=https://term.example.com` | URL público para el túnel con nombre |

### Opciones avanzadas

Daytona configura estas variables para el servidor que ejecuta dentro del entorno aislado. También puede configurarlas usted mismo.

| Variable | Para qué sirve |
|----------|--------------|
| `TERMBRIDGE_HOST=0.0.0.0` | Dirección a la que se vincula el servidor (por defecto, `127.0.0.1`). El URL local que se muestra siempre indica `127.0.0.1`. |
| `TERMBRIDGE_COOKIE_SAMESITE=lax` | Valor `SameSite` de la cookie de sesión: `lax`, `strict` o `none` (por defecto, `Lax`, o `None` en modo directo) |
| `TERMBRIDGE_SHARE_FILE=/path/share-url.txt` | Escribe también el URL compartido en este archivo |
| `TERMBRIDGE_HIDE_TERMINAL_SWITCHER=1` | Oculta el selector de terminales en el UI |
| `TERMBRIDGE_TMUX_PATH_PREFIX=/path/bin` | Anteponer esto a `PATH` en cada sesión de tmux a la que Termbridge se conecte o que inicie (se escribe en la sesión como un comando de `export`) |

### Desarrollo

| Variable | Para qué sirve |
|----------|--------------|
| `TERMBRIDGE_INSECURE_COOKIE=1` | Permite cookies HTTP (solo desarrollo local) |
| `TERMBRIDGE_PROXY_PORT=5173` | Puerto del proxy para el script de dev:beam:proxy |
| `TERMBRIDGE_DEV_UI=http://127.0.0.1:5000` | Anula el Vite de desarrollo de UI URL |
| `TERMBRIDGE_DEV_PORT=3000` | Anula el puerto del servidor de Termbridge en desarrollo (por defecto, `8787`) |
| `TERMBRIDGE_DEV_SESSION=codex` | Nombre de sesión tmux para `dev:beam` (por defecto, `codex`) |
| `TERMBRIDGE_SKIP_BUILD=1` | Omite la compilación de CLI en `dev:beam` |

### Sandbox (Daytona)

| Variable | Para qué sirve |
|----------|--------------|
| `TERMBRIDGE_BACKEND=sandbox-daytona` | Usa el backend de sandbox de Daytona |
| `TERMBRIDGE_SANDBOX_DIRECT=true` | Ejecuta Termbridge dentro del sandbox |
| `TERMBRIDGE_SANDBOX_SERVER_PORT=8080` | Puerto del servidor en el sandbox |
| `TERMBRIDGE_SANDBOX_AGENTS=claude-code,codex` | Instala automáticamente y sincroniza la autenticación de los agentes |
| `TERMBRIDGE_SANDBOX_AGENT_ENV=...` | Variables de entorno adicionales que se reenvían |
| `TERMBRIDGE_SANDBOX_AGENT_AUTH_PATHS=...` | Archivos de autenticación locales que se sincronizan |

Para ver la configuración completa de Daytona, consulta la [guía de Daytona](https://termbridge.inline0.dev/es/docs/sandboxes/daytona).

## Detener Termbridge

Pulsa `Ctrl+C` en la terminal donde se está ejecutando Termbridge. Esto:

- Cierra el túnel (si está habilitado)
- Detiene el servidor local
- Mantiene activas las sesiones de tmux (salvo que hayas usado `--kill-on-exit`)

Tus sesiones de tmux persisten de forma predeterminada, así que puedes volver a conectarte más tarde.