CLI flags reference

Global flags

Every command accepts these, but only send and receive act on them. floe version and floe update parse them and then ignore them, so floe version --server https://floe.example.com is accepted and changes nothing. The one exception is the pair --relay-only and --no-relay, which every command refuses together.

Flag	Default	Description
`--server <url>`	`https://api.floe.one`	Signaling server URL. Use `http://localhost:3001` for local testing or your self-hosted server URL.
`--no-relay`	`false`	Drop every TURN entry from your ICE list, so you offer nothing relayed. It is one-sided: the peer can still offer a relay, and if that path wins the CLI proceeds over it, so pass the flag on both ends when it has to be a guarantee. When no path forms at all the failure is a generic connection error after about 30 seconds, never a message about the relay.
`--relay-only`	`false`	Route everything through the TURN relay and never try a direct path, so the other side sees the relay’s address instead of yours. It is the command-line twin of the desktop app’s Hide my IP address switch, and it applies to your side only. While it is on, the 2 GB relay cap applies to every transfer, even on a network that could have connected directly; see File size limits. It needs a relay to exist: against a server that offers STUN only, the command stops before the transfer starts and names the flag, rather than timing out about 30 seconds later. Cannot be combined with `--no-relay`. Also settable with `FLOE_RELAY_ONLY=1`.
`--web <url>`	(auto-detected)	Web app URL included in the browser link printed by `floe send`. Auto-detected from `--server`: `https://api.floe.one` maps to `https://floe.one`, `http://localhost:3001` maps to `http://localhost:3000`, and any other server maps to itself, on the assumption that one origin serves both the API and the web app. Set `--web` only when your web app has its own hostname.
`--iface <name>`	(all interfaces)	Restrict WebRTC to network interfaces whose name contains this value (case-insensitive). Repeat the flag or separate names with commas, so `--iface Ethernet --iface Wi-Fi` and `--iface Ethernet,Wi-Fi` do the same thing. Use it when a VPN or virtual-machine adapter (Tailscale, VMware, WSL, Hyper-V) slows connection setup. See Troubleshooting.

The desktop app has equivalents for three of these. --server and --web are Server address and Share link address, under Advanced in Settings, and --relay-only is the Hide my IP address toggle under Privacy. --no-relay has no desktop equivalent: Floe Desktop can require the relay but never refuse it. See Desktop app settings.

Help and version flags

These come from the CLI framework rather than from Floe itself.

Flag	Short	Default	Description
`--help`	`-h`	`false`	Print usage and exit. Works on every command, so `floe send --help` and `floe receive --help` each print that command’s own flags.
`--version`	`-v`	`false`	Print the installed version and exit, for example `floe 1.10.11`. Root only: `floe --version` works, `floe send --version` does not. See Alternatives.

floe completion and floe help come from the same place and are not part of Floe’s own interface. Run floe completion --help if you want shell completion.

Environment variables

Floe reads five environment variables. If you run your own signaling server, set it once in your environment instead of passing --server on every command.

Variable	Equivalent flag	Description
`FLOE_SERVER`	`--server`	Signaling server URL, used by every command.
`FLOE_WEB`	`--web`	Web app URL used for the browser link printed by `floe send`.
`FLOE_RELAY_ONLY`	`--relay-only`	Set to `1` to route every transfer through the relay, hiding your IP address from the other side. A typed `--no-relay` overrides it for that one command, since the two can never both be on.
`FLOE_NO_STATS`	`--no-report`	Set to `1` to never report byte counts. Applies to `floe receive`. See Opting out of the global counter.
`FLOE_NO_UPDATE_CHECK`	(no flag)	Set to `1` to suppress the “Update available” hint that `floe version` prints. It does not affect transfers or `floe update` itself.

A flag always beats its variable, so you can override the setting for a single command without unsetting anything:

macOS and Linux

export FLOE_SERVER=https://floe.example.com
floe send photo.jpg                                # uses floe.example.com
floe send photo.jpg --server https://api.floe.one  # the flag wins, just this once

On Windows PowerShell:

Windows

$env:FLOE_SERVER = "https://floe.example.com"
floe send photo.jpg

Trailing slashes are trimmed, so https://floe.example.com/ and https://floe.example.com behave the same. Set FLOE_WEB only when your web app runs on a different host from your signaling server. Leave it unset and share links point at the same host as your server, which is what you want when one domain serves both. The only exceptions are Floe’s own deployment and the local dev pair, which are special-cased to their web hosts as described under --web above.

`floe receive` flags

Specific to the receive command.

Flag	Short	Default	Description
`--output <dir>`	`-o`	`.`	Directory to save received files. Created automatically if it does not exist.
`--yes`	`-y`	`false`	Accept incoming files without the confirmation prompt.
`--no-report`		`false`	Do not report the transferred byte count to Floe’s public global counter. See Opting out of the global counter below.

`floe update` flags

Specific to the update command.

Flag	Default	Description
`--check`	`false`	Report whether a newer release exists and exit without installing it. On an up-to-date binary the flag changes nothing: `floe update` prints `Already up to date (1.10.11)` and stops either way (the installed version carries no leading `v`). On a package-managed install the update guard runs first, so `--check` stops with the upgrade command for your package manager instead of a version report. See Update the CLI.

Opting out of the global counter

After a successful transfer, the receiver sends only the total byte count to the signaling server it is connected to (api.floe.one by default, or your own server when you set --server or FLOE_SERVER) to power the public “transferred globally” counter. No file names, contents, or identity are included. The sender never reports. Errors are ignored, so a failed report never changes the outcome of a transfer. The request goes out after every file is written and the summary has printed, and it carries a 5-second timeout, so an unreachable server can delay floe receive from exiting by a few seconds but never affects the files. To opt out for a single transfer, pass --no-report:

Terminal

floe receive olive-tiger-castle --no-report

To opt out permanently, set FLOE_NO_STATS=1 in your environment (for example in your shell profile):

Terminal

export FLOE_NO_STATS=1
floe receive olive-tiger-castle

When opted out, no request is sent to the server and the global counter is not incremented for that transfer. The transfer itself is unaffected. In the desktop app the same choice is the Contribute to global stats toggle in Settings, and turning it off is the equivalent of --no-report.

Exit codes

Code	Meaning
`0`	Success. Also what `floe update` returns on a build compiled from source, which prints `Cannot update a dev build.` and stops.
`1`	Any error: a transfer that failed, a code that would not resolve, a declined transfer, or a package-managed install refusing to self-update.
`130`	Interrupted, by `Ctrl+C` or by `SIGTERM`. Floe prints `Canceled.` to stderr and removes the `.part` file it was writing.

floe with no arguments prints help and exits 0.

Timeouts

Floe gives up rather than hanging, and the limits differ by phase. The ones you are most likely to meet:

Phase	Limit
Establishing the connection	30 seconds, then `timed out establishing a connection`
Receiver connected, sender never starts	30 seconds, then `connected, but no data arrived from the sender within 30s`
Sender waiting for the receiver to accept	120 seconds, sized for a human answering the `Accept? [Y/n]` prompt
A transfer that stops making progress	60 seconds
The byte-count report after a transfer	5 seconds, and it never affects the files

A floe receive can sit for up to about ten seconds after printing its summary. That is a five-second grace period so the final acknowledgement reaches the sender, plus the report. The full list is in the transfer protocol reference.

Examples

Use a local dev server for both sender and receiver:

Terminal

floe send photo.jpg --server http://localhost:3001
floe receive olive-tiger-castle --server http://localhost:3001

Disable relay fallback (direct connections only):

Terminal

floe send photo.jpg --no-relay

Hide your IP address from the other side by forcing the relay (the 2 GB cap applies):

Terminal

floe send photo.jpg --relay-only

Point the browser link at a custom web client:

Terminal

floe send photo.jpg --server https://api.example.com --web https://app.example.com

Save received files to a specific folder and auto-accept:

Terminal

floe receive olive-tiger-castle -o ~/Downloads -y

See Use a self-hosted server for more server configuration examples.

Getting started

Core concepts

Web app

Desktop app

CLI

Self-hosting

Help

Reference

Changelog

CLI flags reference

Global flags

Help and version flags

Environment variables

`floe receive` flags

`floe update` flags

Opting out of the global counter

Exit codes

Timeouts

Examples

​Global flags

​Help and version flags

​Environment variables

​floe receive flags

​floe update flags

​Opting out of the global counter

​Exit codes

​Timeouts

​Examples

Global flags

Help and version flags

Environment variables

`floe receive` flags

`floe update` flags

Opting out of the global counter

Exit codes

Timeouts

Examples