CLI reference

Usage

tui-bridge <command> [args...]                Run a TUI and expose it on the web
tui-bridge [options] <command> [args...]      Options before the command
tui-bridge start -- <command> [args...]       Explicit form (optional)
tui-bridge -- <command> [args...]             Use -- to pass flags to the TUI

Examples

tui-bridge opencode
tui-bridge htop
tui-bridge lazygit
tui-bridge "npm run dev"
tui-bridge --lan opencode
tui-bridge -- opencode --verbose

Options

Flag	Description
--no-tunnel	Skip cloudflared; local-only (or --lan) access.
--lan	Bind to 0.0.0.0 and use your LAN IP (phone on same WiFi). Use when cloudflared is not installed. Implies --no-tunnel.
--no-pause	Do not wait for Enter before opening the TUI (default pauses so you can scan the QR code while it stays on screen).
--no-update-check	Skip the npm registry version check.
--update	Update tui-bridge to the latest npm release and exit.
--web-root <dir>	Serve web assets from <dir> instead of the bundled build.
-v, --verbose	Verbose logging.
-V, --version	Print version and exit.
-h, --help	Show help.

The -- separator

Use -- to forward flags to the target TUI itself:

tui-bridge -- opencode --verbose

Everything after -- is passed verbatim to the TUI and never parsed by tui-bridge.

Local terminal

Both local and mobile can type simultaneously — there is no input lock. The phone always mirrors the desktop terminal’s grid (scrolling horizontally on a narrow viewport); there is no “fit” button. Resizing your local terminal window updates the shared PTY and every connected phone reflows automatically.

Update check

On every launch, tui-bridge checks the npm registry for a newer release (cached for 24 hours in ~/.tui-bridge/update-check.json). When a newer version exists, a banner is printed to stderr on the QR / pause screen:

+---------------------------------------------+
| tui-bridge update available  0.1.7 -> 0.1.8 |
| Run: npm i -g tui-bridge                    |
+---------------------------------------------+

The check never blocks startup and is silent on failure (offline, timeout, bad response). Pre-release versions on either side are skipped.

Skip the check

tui-bridge --no-update-check opencode
# or via environment variable:
TUI_BRIDGE_NO_UPDATE_CHECK=1 tui-bridge opencode

Self-update

tui-bridge --update

Fetches the latest version from npm and, if newer, runs npm i -g tui-bridge (its progress is streamed live). Prints one of:

• Updated tui-bridge 0.1.7 -> 0.1.8. Re-run your command. (success)
• tui-bridge is already up to date (0.1.7) (nothing to do)
• Could not reach npm registry. Check your connection. (offline / error)

--update is a short-circuit: it does not require a target command and exits immediately after.

Notes

• The TUI runs in your current working directory, so run tui-bridge from the folder you want to work in.
• The pairing URL is also saved to ~/.tui-bridge/session-url.txt in case the TUI overwrites the screen before you finish scanning.