flinch-cli

Stream your terminal to Flinch — readable, colorful, real-time terminal streaming for live coding sessions.

What it does

flinch-cli captures your terminal output (including colors, cursor movement, and all ANSI sequences) and streams it to your Flinch room in real-time. Viewers see a pixel-perfect rendering of your terminal — not a blurry video, but actual text they can read and copy.

Works with any terminal program: bash, zsh, fish, Claude Code, Cursor, vim, node, python, cargo — if it runs in a terminal, Flinch streams it.

Install

npm install -g flinch-cli

Requirements: Node.js 18–23 (not 24+), macOS/Linux (Windows support coming).

Node 24 hang: @livekit/rtc-node never finishes room.connect on Node 24+. If the CLI stalls on Connecting to LiveKit..., run nvm use 22 (or install Node 22) and rebuild/reinstall the CLI.

Usage

Stream your terminal

# Start streaming to a room
flinch stream AXKF1234

# Multi-terminal: same join code, different --name → multiple viewer panes
flinch stream AXKF1234 --name editor
flinch stream AXKF1234 --name build   # second shell / second tab

# Use a specific shell
flinch stream AXKF1234 --shell /bin/fish

# Local development
flinch stream AXKF1234 --server http://localhost:3000

Once running, your terminal works exactly as normal. Type commands, run Claude Code, write code — everything is streamed live to viewers.

Secrets: common API keys / tokens / passwords are masked for viewers (you still see them locally). Not perfect across split packets — treat as best-effort.

Stop streaming: Press Ctrl+D or type exit. The viewer pane clears when the session ends (no linger).

How viewers see it

Viewers see a <TerminalView /> panel on the stream page powered by xterm.js. It renders your terminal with:

• Full 256-color and truecolor support
• Flinch-branded dark theme (Geist Mono font)
• Clickable URLs
• Copy button for terminal content
• Expand/collapse to focus on the terminal
• 5000 lines of scrollback

Using with Claude Code

# Start streaming
flinch stream AXKF1234

# Inside the streamed terminal, just use Claude normally
claude

# Viewers see everything: your prompts, Claude's streaming output,
# tool calls, code generation — all in readable text, not a video

Using with Cursor / VS Code

Open the integrated terminal in your editor, then:

flinch stream AXKF1234

The CLI wraps your shell, so anything that runs inside it (including the editor's terminal) is captured.

How it works

1. PTY capture: The CLI spawns a pseudo-terminal (PTY) using node-pty, wrapping your shell
2. Stream to LiveKit: Terminal output is buffered (~50ms batches) and sent via LiveKit text streams (topic: "terminal")
3. Viewer rendering: The Flinch web app receives the stream via LiveKit data channels and renders it in xterm.js
4. Your terminal is unaffected: You type and interact normally — the CLI just mirrors the output

Options

| Flag | Description | Default | | ----------------- | --------------------------------- | ------------------------ | | [code] | Go Live join code | Required | | --room <slug> | Deprecated; requires --token | — | | --server <url> | Flinch server URL | https://joinflinch.com | | --token <token> | LiveKit token (skips server auth) | — | | --shell <shell> | Shell to use | $SHELL or /bin/zsh | | --cols <n> | Terminal columns | Current terminal width | | --rows <n> | Terminal rows | Current terminal height |

Environment variables

| Variable | Description | | ------------------------- | ------------------------------ | | FLINCH_SERVER | Default server URL | | LIVEKIT_URL | LiveKit WebSocket URL | | NEXT_PUBLIC_LIVEKIT_URL | LiveKit WebSocket URL fallback | | SHELL | Default shell to spawn |

Auth status

Publishing uses the join code from the Go Live page. flinch login is intentionally a stub for now; device pairing is not implemented yet.

Supported platforms

• macOS: Full support (Intel + Apple Silicon)
• Linux: Full support (x64 + arm64)
• Windows: Coming soon (needs Windows PTY support)

Supported terminals

Everything. The PTY layer captures raw output from any program:

• Shells: bash, zsh, fish, nushell, powershell
• AI tools: Claude Code, Cursor terminal, GitHub Copilot CLI, Aider
• Editors: vim, neovim, helix, nano, emacs
• Languages: node, python, ruby, go, rust, cargo
• Tools: git, docker, kubectl, terraform

If it produces output in a terminal, Flinch streams it.