Referência de CLI

Ver como Markdown Editar no GitHub Documentação em 1675df8

Uso básico

Basta executar o comando, sem argumentos:

Shell

npx termbridge

Isso inicia tudo: servidor local, sessão tmux e túnel padrão Cloudflare.

Executar termbridge sem um subcomando equivale a termbridge start.

Você também pode executar termbridge start explicitamente com todas as flags:

Shell

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

Flags

Flag	O que faz	Padrão
`--port <port>`	Usa uma porta específica em vez de uma aleatória	Aleatória
`--proxy <port>`	Encaminha por proxy um servidor de desenvolvimento local (habilita as visualizações Terminal/Preview)	-
`--session <name>`	Dá um nome à sua sessão tmux	Gerado automaticamente
`--kill-on-exit`	Limpa sessões tmux quando Termbridge é encerrado	Desativado
`--no-qr`	Não exibe o código QR (útil para scripts)	Desativado
`--no-tunnel`	Desativa o túnel (requer `--public-url`)	Desativado
`--public-url <url>`	URL público quando o túnel está desativado	-
`--tunnel <provider>`	Provedor de túnel (`cloudflare` ou `none`)	cloudflare
`--tunnel-token <token>`	Usa um token de túnel Cloudflare nomeado (requer `--port`)	-
`--tunnel-url <url>`	URL público para o túnel nomeado (obrigatório com `--tunnel-token`)	-
`--backend <backend>`	Backend do terminal (`tmux` ou `sandbox-daytona`)	tmux
`--sandbox-repo <url>`	URL do repositório a clonar no sandbox Daytona	-
`--sandbox-branch <branch>`	Branch a verificar no sandbox	-
`--sandbox-path <path>`	Caminho do repositório no sandbox	Derivado do nome do repositório
`--sandbox-name <name>`	Nome do sandbox	`termbridge-<hex>` aleatório
`--sandbox-preview-port <port>`	Porta de visualização no sandbox	-
`--sandbox-public`	Cria um sandbox público	Desativado (ativado no modo direto)
`--sandbox-direct`	Executa o servidor no sandbox Daytona (sem túnel)	Desativado
`--dev-proxy-url <url>`	Encaminha o tráfego de visualização por proxy para este URL em vez de `localhost:<proxy port>` (usado pelos scripts de desenvolvimento)	-
`-h`, `--help`	Exibe o texto de ajuda	-

Qualquer outra opção gera unknown option: <flag>. Não existe uma flag --version.

Uma flag tem precedência sobre sua variável de ambiente, com uma exceção: TERMBRIDGE_TUNNEL atualmente substitui --tunnel e --no-tunnel (#5).

Observação A saída integrada de termbridge --help ainda lista flags --daytona-* e --backend tmux | daytona. Esses nomes são rejeitados; use as flags --sandbox-* e --backend sandbox-daytona da tabela acima (#1).

Exemplos

Conectar-se a uma sessão tmux existente

Se você já tiver uma sessão tmux em execução:

Shell

termbridge --session my-session

Porta fixa e sessão personalizada

Shell

termbridge --port 8080 --session codex

Encerramento limpo (sem sessões remanescentes)

Shell

termbridge --kill-on-exit

Scripts (sem saída QR)

Shell

termbridge --no-qr

Encaminhar por proxy um servidor de desenvolvimento Vite

Shell

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

# Then start Termbridge with proxy
termbridge --proxy 5173

Use o botão Views para alternar entre Terminal e Preview. Preview carrega seu aplicativo pelo proxy com suporte a HMR.

Túnel Cloudflare nomeado (baseado em token)

Se você tem uma conta Cloudflare e quer evitar os limites de taxa do trycloudflare:

Shell

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

Desativar o túnel (usar seu próprio URL público)

Shell

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

Variáveis de ambiente

Termbridge lê as variáveis de ambiente do shell e de um arquivo .env no diretório de onde é executado. As variáveis já definidas no shell têm precedência sobre as do arquivo .env.

Configurações principais

Variável	O que faz
`TERMBRIDGE_SESSIONS=2`	Cria várias sessões tmux na inicialização
`TERMBRIDGE_TMUX_CWD=/path`	Diretório de trabalho para novas sessões tmux
`TERMBRIDGE_PUBLIC_URL=https://example.com`	URL público quando o túnel está desativado
`TERMBRIDGE_TUNNEL=none`	Desativa o túnel
`TERMBRIDGE_TUNNEL_TOKEN=<token>`	Token de túnel nomeado (requer `TERMBRIDGE_TUNNEL_URL`)
`TERMBRIDGE_TUNNEL_URL=https://term.example.com`	URL público para o túnel nomeado

Avançado

Daytona define estes valores para o servidor executado dentro do sandbox. Você também pode defini-los manualmente.

Variável	O que faz
`TERMBRIDGE_HOST=0.0.0.0`	Endereço ao qual o servidor se vincula (padrão: `127.0.0.1`). O URL local exibido sempre mostra `127.0.0.1`.
`TERMBRIDGE_COOKIE_SAMESITE=lax`	Valor `SameSite` do cookie de sessão: `lax`, `strict` ou `none` (padrão: `Lax` ou `None` no modo direto)
`TERMBRIDGE_SHARE_FILE=/path/share-url.txt`	Também grava o URL de compartilhamento neste arquivo
`TERMBRIDGE_HIDE_TERMINAL_SWITCHER=1`	Oculta o alternador de terminais na UI
`TERMBRIDGE_TMUX_PATH_PREFIX=/path/bin`	Prefixo adicionado a `PATH` em cada sessão tmux que Termbridge inicia ou à qual se conecta (digitado na sessão como um comando `export`)

Desenvolvimento

Variável	O que faz
`TERMBRIDGE_INSECURE_COOKIE=1`	Permite cookies HTTP (somente para desenvolvimento local)
`TERMBRIDGE_PROXY_PORT=5173`	Porta do proxy para o script dev:beam:proxy
`TERMBRIDGE_DEV_UI=http://127.0.0.1:5000`	Substitui o Vite de desenvolvimento UI URL
`TERMBRIDGE_DEV_PORT=3000`	Substitui a porta do servidor Termbridge no desenvolvimento (padrão: `8787`)
`TERMBRIDGE_DEV_SESSION=codex`	Nome da sessão tmux para `dev:beam` (padrão: `codex`)
`TERMBRIDGE_SKIP_BUILD=1`	Ignora a compilação CLI em `dev:beam`

Sandbox (Daytona)

Variável	O que faz
`TERMBRIDGE_BACKEND=sandbox-daytona`	Usa o backend de sandbox Daytona
`TERMBRIDGE_SANDBOX_DIRECT=true`	Executa Termbridge dentro do sandbox
`TERMBRIDGE_SANDBOX_SERVER_PORT=8080`	Porta do servidor no sandbox
`TERMBRIDGE_SANDBOX_AGENTS=claude-code,codex`	Instala automaticamente e sincroniza a autenticação dos agentes
`TERMBRIDGE_SANDBOX_AGENT_ENV=...`	Variáveis de ambiente extras a encaminhar
`TERMBRIDGE_SANDBOX_AGENT_AUTH_PATHS=...`	Arquivos de autenticação locais a sincronizar

Para ver a configuração completa de Daytona, consulte o guia Daytona.

Parar Termbridge

Pressione Ctrl+C no terminal em que Termbridge está em execução. Isso:

Fecha o túnel (se estiver ativado)
Para o servidor local
Mantém as sessões tmux ativas (a menos que você tenha usado --kill-on-exit)

Por padrão, suas sessões tmux persistem, para que você possa se reconectar mais tarde.