CLI reference

Examples use npx flash-tunnel. With a project dependency use pnpm exec flash-tunnel; with a global installation use flash-tunnel directly.

Commands

Command	Purpose
`flash-tunnel [root]`	Start a preview; optional positional project directory
`flash-tunnel start`	Explicit start command
`flash-tunnel doctor`	Check Node, config, credentials, zone, cloudflared, ports, and sessions
`flash-tunnel init`	Create `flash-tunnel.ts`
`flash-tunnel clean`	List or clean recorded sessions
`flash-tunnel providers`	List available adapters and capabilities

Use --help for command usage and --version for the installed version.

Flag	Meaning
`--cwd <dir>`	Project directory
`--config <path>`	Explicit config file
`--port <port>`	Preferred local port
`--command <command>`	Command to start the server
`--url <url>`	Existing server URL
`--attach`	Only attach; requires `--url`
`--static [dir]`	Serve a directory; detect build output if omitted
`--dev`	Force the dev script instead of preview
`--build`	Run the build script first
`--reuse`	Reuse a server already listening on the port

Flag	Meaning
`--mode <mode>`	`named` (default) or `quick`
`--zone <domain>`	Cloudflare zone, e.g. `example.com`
`--hostname <fqdn>`	Full public hostname; takes precedence over zone/subdomain generation
`--subdomain <label>`	Literal label or template
`--allow-multilevel`	Allow multi-level subdomains; requires appropriate certificate coverage
`--overwrite`	Replace DNS records not created by this tool
`--auto-stop <duration>`	Stop and clean up after a duration, e.g. `30m`, `2h`
`--keep`	Retain cloud DNS/tunnel resources on exit
`--no-sweep`	Skip startup scanning of stale sessions

Flag	Meaning
`--dry-run`	Print effective config and sources without creating resources
`--json`	Emit NDJSON to stdout
`--ready-file <path>`	Write the ready payload to a JSON file
`--on-ready <command>`	Run a command once ready
`--open`	Open a browser when ready in an interactive terminal
`--no-open`	Do not open a browser (default)
`--verbose`	Stream server and cloudflared logs
`--silent`	Only print errors
`--no-color`	Disable terminal colors
`--no-spinner`	Disable the spinner
`-y, --yes`	Disable prompts and use defaults

--open is suppressed in JSON mode, CI, non-TTY output, or when FLASH_TUNNEL_NO_OPEN=1.

With no selector, clean lists sessions. Use selectors to remove resources:

Flag	Meaning
`--session <id>`	Select one session
`--project <dir>`	Select sessions for a project
`--stale`	Select sessions whose owning process has gone
`--all`	Select every recorded session; requires `--yes`
`--dry-run`	Show planned removals
`--yes`	Confirm broad cleanup
`--force`	Allow cleanup of a running session
`--json` / `--silent`	Machine-readable / errors-only output