# CLI 참조

## 기본 사용법

명령만 실행하면 됩니다. 인수는 필요하지 않습니다:

```bash
npx termbridge
```

이 명령은 로컬 서버, tmux 세션, 기본 Cloudflare 터널 등 모든 항목을 시작합니다.

하위 명령 없이 `termbridge`을 실행하는 것은 `termbridge start`을 실행하는 것과 같습니다.

모든 플래그를 지정해 `termbridge start`을 명시적으로 실행할 수도 있습니다:

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

## 플래그

| 플래그 | 기능 | 기본값 |
|------|--------------|---------|
| `--port <port>` | 임의 포트 대신 특정 포트 사용 | 임의 |
| `--proxy <port>` | 로컬 개발 서버 프록시(Terminal/Preview 뷰 활성화) | - |
| `--session <name>` | tmux 세션 이름 지정 | 자동 생성 |
| `--kill-on-exit` | Termbridge 종료 시 tmux 세션 정리 | 끔 |
| `--no-qr` | QR 코드 출력 안 함(스크립트에 유용) | 끔 |
| `--no-tunnel` | 터널 비활성화(`--public-url` 필요) | 끔 |
| `--public-url <url>` | 터널 비활성화 시 공개 URL | - |
| `--tunnel <provider>` | 터널 제공자(`cloudflare` 또는 `none`) | cloudflare |
| `--tunnel-token <token>` | 이름이 지정된 Cloudflare Tunnel 토큰 사용(`--port` 필요) | - |
| `--tunnel-url <url>` | 이름이 지정된 터널의 공개 URL(`--tunnel-token`와 함께 필수) | - |
| `--backend <backend>` | 터미널 백엔드(`tmux` 또는 `sandbox-daytona`) | tmux |
| `--sandbox-repo <url>` | Daytona 샌드박스에 복제할 저장소 URL | - |
| `--sandbox-branch <branch>` | 샌드박스에서 체크아웃할 브랜치 | - |
| `--sandbox-path <path>` | 샌드박스 내 저장소 경로 | 저장소 이름에서 파생 |
| `--sandbox-name <name>` | 샌드박스 이름 | 임의 `termbridge-<hex>` |
| `--sandbox-preview-port <port>` | 샌드박스 내 미리보기 포트 | - |
| `--sandbox-public` | 공개 샌드박스 생성 | 끔(직접 모드에서는 켜짐) |
| `--sandbox-direct` | Daytona 샌드박스 안에서 서버 실행(터널 없음) | 끔 |
| `--dev-proxy-url <url>` | 개발 스크립트에서 사용하는 `localhost:<proxy port>` 대신 이 URL로 미리보기 트래픽 프록시 | - |
| `-h`, `--help` | 도움말 출력 | - |

다른 옵션은 `unknown option: <flag>` 오류를 발생시킵니다. `--version` 플래그는 없습니다.

플래그는 환경 변수보다 우선합니다. 예외는 하나로, 현재 `TERMBRIDGE_TUNNEL`이 `--tunnel` 및 `--no-tunnel`보다 우선합니다([#5](https://github.com/inline0/termbridge/issues/5)).

> **참고**
> 내장된 `termbridge --help` 출력에는 여전히 `--daytona-*` 플래그와 `--backend tmux | daytona`가 표시됩니다. 이 이름은 거부되므로 위 표의 `--sandbox-*` 플래그와 `--backend sandbox-daytona`를 사용하세요([#1](https://github.com/inline0/termbridge/issues/1)).

## 예시

### 기존 tmux 세션에 연결

이미 실행 중인 tmux 세션이 있다면:

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

### 고정 포트 및 사용자 지정 세션

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

### 깔끔하게 종료(세션 잔여 없음)

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

### 스크립팅(QR 출력 없음)

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

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

**Views** 버튼을 사용해 Terminal과 Preview 사이를 전환하세요. Preview는 HMR을 지원하는 프록시를 통해 앱을 불러옵니다.

### 이름이 지정된 Cloudflare 터널(토큰 기반)

Cloudflare 계정이 있고 trycloudflare 요청 제한을 피하려면:

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

### 터널 비활성화(자체 공개 URL 사용)

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

## 환경 변수

Termbridge은 셸과 실행 디렉터리의 `.env` 파일에서 환경 변수를 읽습니다. 셸에 이미 설정된 변수는 `.env` 파일보다 우선합니다.

### 핵심 설정

| 변수 | 기능 |
|----------|--------------|
| `TERMBRIDGE_SESSIONS=2` | 시작 시 여러 tmux 세션 생성 |
| `TERMBRIDGE_TMUX_CWD=/path` | 새 tmux 세션의 작업 디렉터리 |
| `TERMBRIDGE_PUBLIC_URL=https://example.com` | 터널 비활성화 시 공개 URL |
| `TERMBRIDGE_TUNNEL=none` | 터널 비활성화 |
| `TERMBRIDGE_TUNNEL_TOKEN=<token>` | 이름이 지정된 터널 토큰(`TERMBRIDGE_TUNNEL_URL` 필요) |
| `TERMBRIDGE_TUNNEL_URL=https://term.example.com` | 이름이 지정된 터널의 공개 URL |

### 고급 설정

Daytona 직접 모드는 샌드박스 안에서 실행하는 서버에 이 값을 설정합니다. 직접 설정할 수도 있습니다.

| 변수 | 기능 |
|----------|--------------|
| `TERMBRIDGE_HOST=0.0.0.0` | 서버가 바인딩하는 주소(기본값 `127.0.0.1`). 출력되는 로컬 URL에는 항상 `127.0.0.1`이 표시됩니다. |
| `TERMBRIDGE_COOKIE_SAMESITE=lax` | 세션 쿠키의 `SameSite` 값: `lax`, `strict` 또는 `none`(기본값 `Lax`, 직접 모드에서는 `None`) |
| `TERMBRIDGE_SHARE_FILE=/path/share-url.txt` | 공유 URL도 이 파일에 기록 |
| `TERMBRIDGE_HIDE_TERMINAL_SWITCHER=1` | UI에서 터미널 전환기 숨기기 |
| `TERMBRIDGE_TMUX_PATH_PREFIX=/path/bin` | 각 tmux 세션에서 Termbridge이 시작하거나 연결할 때 `PATH` 앞에 추가(세션에 `export` 명령으로 입력) |

### 개발

| 변수 | 기능 |
|----------|--------------|
| `TERMBRIDGE_INSECURE_COOKIE=1` | HTTP 쿠키 허용(로컬 개발 전용) |
| `TERMBRIDGE_PROXY_PORT=5173` | dev:beam:proxy 스크립트의 프록시 포트 |
| `TERMBRIDGE_DEV_UI=http://127.0.0.1:5000` | Vite 개발 UI URL 재정의 |
| `TERMBRIDGE_DEV_PORT=3000` | 개발 중 Termbridge 서버 포트 재정의(기본값 `8787`) |
| `TERMBRIDGE_DEV_SESSION=codex` | `dev:beam`의 tmux 세션 이름(기본값 `codex`) |
| `TERMBRIDGE_SKIP_BUILD=1` | `dev:beam`에서 CLI 빌드 건너뛰기 |

### 샌드박스(Daytona)

| 변수 | 기능 |
|----------|--------------|
| `TERMBRIDGE_BACKEND=sandbox-daytona` | Daytona 샌드박스 백엔드 사용 |
| `TERMBRIDGE_SANDBOX_DIRECT=true` | 샌드박스 안에서 Termbridge 실행 |
| `TERMBRIDGE_SANDBOX_SERVER_PORT=8080` | 샌드박스 내 서버 포트 |
| `TERMBRIDGE_SANDBOX_AGENTS=claude-code,codex` | 에이전트용 인증 자동 설치 및 동기화 |
| `TERMBRIDGE_SANDBOX_AGENT_ENV=...` | 전달할 추가 환경 변수 |
| `TERMBRIDGE_SANDBOX_AGENT_AUTH_PATHS=...` | 동기화할 로컬 인증 파일 |

전체 Daytona 설정은 [Daytona 가이드](https://termbridge.inline0.dev/ko/docs/sandboxes/daytona)를 참조하세요.

## Termbridge 중지

Termbridge이 실행 중인 터미널에서 `Ctrl+C`을 누르세요. 그러면 다음 작업이 수행됩니다:

- 터널을 닫습니다(활성화된 경우)
- 로컬 서버를 중지합니다
- tmux 세션은 유지합니다(`--kill-on-exit`을 사용한 경우 제외)

기본적으로 tmux 세션은 유지되므로 나중에 다시 연결할 수 있습니다.