CLI

Command reference.

farwing is the free program: a client with no limit on how many copies run at once, plus a small helper started on the remote side. Without a license file, all copies on one machine share 1 Gbit/s in total, including when --max-rate is set higher. Copies to or from a licensed Farwing Server run at the server's licensed speed. For the full flag list on your install, run farwing --help and farwing cp --help.

Commands

Command	Purpose
`farwing cp`	Copy files and directories. One side is `[user@]host:path` over SSH, or `farwing://host[:port]/path` for a `farwing listen`, or use `--ticket`.
`farwing get`	Download every file in a package from its link, or one file from a space: `Marketing:/2026/launch.mov`.
`farwing send`	Send files to a receive link, or into a space: `Marketing:/incoming/reel.mov`.
`farwing spaces`	List the spaces you can open. My files is listed first.
`farwing ls`	List a folder in a space. `~` is My files.
`farwing bench`	Memory-to-memory speed test against a host over SSH, or against a `farwing listen` (no disk).
`farwing doctor`	Find what limits transfers: disks, processor and network. Add `[user@]host` to check the far end too.
`farwing daemon`	Own the data port so every transfer on this host shares it.
`farwing listen`	Serve one folder to copies that use a shared key file, with no SSH. See Copying without SSH.
`farwing keygen`	Print a new random key for listen mode (64 hex digits).
`farwing serve`	Remote helper started by the client over SSH. Not for direct use.

farwing cp

farwing cp SRC [SRC ...] DST
farwing cp --key-file KEY SRC [SRC ...] DST
farwing cp --ticket TICKET LOCAL_PATH [LOCAL_PATH ...]

As with scp, the sources come first and the destination last, and the side written as a remote path is the other machine. That is how a copy knows which way to go:

Remote path	The other machine is
`[user@]host:path`	A computer you can sign in to over SSH. Farwing signs in, starts itself there, and sends the data over its own fast connection. See Signing in over SSH.
`farwing://host[:port]/path`	A computer running `farwing listen`, reached with `--key-file` and no SSH. See Copying without SSH.

Flag	Meaning
`--ticket`	Transfer ticket from a Farwing Server.
`--ticket-host`	Connect somewhere other than the address in the ticket.
`--no-verify`	Skip the whole-file BLAKE3 check at the end.
`--fsync`	Flush the file to disk before reporting success.
`--no-resume`	Start over instead of continuing a partial file.
`--no-retry`	Give up after the first failure.
`--retry-max`	Tries in all, counting the first one.
`--retry-for`	Stop retrying after this long (`s`/`m`/`h`).

A copy to user@host:path signs in the way ssh does on your computer: with your usual keys, your SSH agent and ~/.ssh/config. Leave out user@ and it signs in with your own user name, or the one your SSH config sets for that host.

farwing cp big.iso [email protected]:/data/
farwing cp -i ~/.ssh/lab_ed25519 big.iso [email protected]:/data/

A key file. -i FILE (also --identity or --ssh-key) uses that private key, as ssh -i does. If the key has a passphrase, you are asked for it once.

A password. If the other computer accepts password sign-in and no key works, you are asked for the password once per copy. A copy can open more than one SSH connection, and every one of them uses what you typed, on Windows, macOS and Linux alike. The password stays in memory on your computer only until those connections are open, and is then erased. It goes nowhere except to ssh. If it is wrong, you are asked again.

Without a prompt, for a script or a quick test:

export FW_PASSWORD='…'
farwing cp --password-env FW_PASSWORD big.iso [email protected]:/data/
farwing cp --password-file ~/.config/lab-password big.iso [email protected]:/data/

--password-file reads the first line of the file. On Linux and macOS the file must be readable only by you (chmod 600), or the copy stops before it connects. If the other computer refuses the password, Farwing does not send it again, so a wrong password cannot use up your attempts there. There is no flag that takes the password itself: a password typed into a command is saved in your shell history and can be seen by other programs on the computer.

SSH keys are safer than passwords and need nothing typed. For everyday use, set up a key and an SSH agent.

Copying without SSH

Where you cannot or do not want to sign in over SSH, for example between two lab machines, run farwing listen on one of them. It serves one folder to anyone who has the same key file, and nothing outside that folder.

# once: make a key, and put the same file on both machines
farwing keygen > lab.key

# on the machine that serves the folder
farwing listen --bind 0.0.0.0:47710 --key-file lab.key --dir /srv/incoming

On the other machine, name the listener as farwing://host[:port]/path. The path is inside the listener's folder. Leave the port out if the listener uses the default, 47700. As with every copy, the sources come first and the destination last:

# fetch a file from the listener's folder into the current folder
farwing cp --key-file lab.key farwing://203.0.113.10:47710/CentOS.iso .

# fetch it under another name
farwing cp --key-file lab.key farwing://203.0.113.10:47710/CentOS.iso my.iso

# send a file into the listener's folder, keeping its name
farwing cp --key-file lab.key my.iso farwing://203.0.113.10:47710/

# send it under another name, or into a folder inside the listener's folder
farwing cp --key-file lab.key my.iso farwing://203.0.113.10:47710/CentOS.iso
farwing cp --key-file lab.key my.iso photos/ farwing://203.0.113.10:47710/incoming/

You write	What happens on the listener
`farwing://host/`	The files arrive in the listener's folder under their own names.
`farwing://host/incoming/`	The files arrive in the `incoming` folder, which must already exist.
`farwing://host/CentOS.iso`	If `CentOS.iso` is an existing folder, the files go in it. Otherwise what you send is saved as `CentOS.iso`.

Both machines need the same key file. Anyone with it can read and write the listener's folder, so keep it like a password.
Data goes over UDP, on the one port the listener uses. Open that UDP port to the listener. A copy into the listener's folder under the files' own names can also use TCP on the same port when UDP is blocked.
A listener from an older farwing may not be able to send files, or save one under another name. In that case the copy stops before any data moves and says to update farwing on that machine.
Write an IPv6 address in brackets: farwing://[2001:db8::5]:47710/CentOS.iso. A name with spaces needs only your shell's quotes: "farwing://host/My Film.mov".
farwing listen --sink discards what it receives, for speed tests: farwing bench farwing://host:47710 --key-file lab.key.

Tickets from a Farwing Server

In the portal, choose Upload in a folder, then Terminal. The portal shows one command with a ticket for that folder. The same ticket uploads any number of files and folders in one transfer:

cd ~/Shoot-0412
farwing cp --ticket "$TICKET" .
farwing cp --ticket "$TICKET" notes.txt cuts/ final.mov

You pass	What lands in the server folder
`.`	Everything inside the current folder, hidden files included, with its folders kept. The current folder's own name is not added.
`photos/.`	Everything inside `photos`, without a `photos` folder around it.
`photos` or `photos/`	A folder called `photos` with everything in it.
`a.txt b.mov`	Those files, side by side.

Nothing on the server is replaced. If a file with the same name is already in the folder, the server says which one before any bytes move, and nothing from that transfer is added. Files appear in the folder only once the whole transfer has arrived and checked out. Symbolic links are left out.

A ticket has to be used before the time the portal shows. Your administrator sets that time, and it is 10 minutes unless they change it. A transfer that has started runs to the end however long it takes. If it is interrupted, run the same command again with the same ticket: it carries on from where it stopped, for up to 24 hours after the ticket was first used. The ticket only ever reaches that one folder, for the person who asked for it, in that direction. When a ticket has run out, the command says so; ask the portal for a new one.

Downloads work the same way the other way round: the portal gives a ticket for a file, and farwing cp --ticket "$TICKET" . saves it in the current folder.

Tickets for a whole folder need farwing 0.1.2 or later. An older copy says to update when it is given one.

farwing get

Someone sent you a package from a Farwing Server. Pass the link from the email, and every file in the package downloads into the folder you name, with its folders kept as they are. Without a folder, files go into the current one. No account is needed.

farwing get LINK [FOLDER] [--passcode CODE]

Flag	Meaning
`--passcode`	The passcode, if the package has one. The sender gives it to you separately; it is never in the email.
`--insecure`	Accept a server certificate that does not verify, such as a self-signed one. Use it only for a server you know.
`--https-only`	Download over HTTPS only, without the data port.

Files travel over the server's data port at full speed and fall back to HTTPS when that port is not reachable. Files already downloaded in full are skipped and partial files resume, so running the same command again finishes an interrupted download. The rate and transport flags below apply as well. Each file counts as a download on the sender's record, just as it does in a browser. A link that has expired or been revoked stops working at once.

farwing doctor

A transfer goes only as fast as the slowest part of its path. farwing doctor times the disks, the processor and the network on this machine and says which part is the limit. It is the same check the speed check in the portal runs, and it prints the same verdict and the same report as text. It works on the free program, with no license and no server.

farwing doctor [HOST] [--path FOLDER ...] [--size SIZE]

Without a folder it tests the current folder. It writes one test file into a hidden folder inside each folder it tests, times it, and deletes it. The test file is 512 MB by default, which keeps the check short on a laptop; pass --size 2G for the longer test the server runs. A folder without enough free space is skipped, and the report says why.

Flag	Meaning
`--path`	A folder to test on this machine. Repeat it to test several. Default: the current folder.
`--size`	Size of the test file written in each folder (`k`/`m`/`g`/`t` suffixes). Default `512M`.
`--far-path`	A folder to test on the far end. Repeat it to test several. Default: the folder SSH logs in to.
`-q` / `--quiet`	No progress.

The report goes to standard output, so farwing doctor > report.txt saves exactly the text the portal's Download report button gives. Progress and the one-sentence verdict go to standard error, so you see them while the report is redirected. The check takes about a minute for one folder.

Test files are removed when the check ends. If you stop it with Ctrl+C, it removes them before it exits. If it was ever killed without the chance to, the next run removes what was left.

farwing doctor user@host also checks the far end. It signs in over SSH, runs farwing doctor there, and prints that machine's report after this one's. The far end needs the same farwing installed; use --remote-path if it is not on the default path there. The SSH options -P, -i, -o and --ssh apply. To check a machine you cannot sign in to, run farwing doctor on it yourself and compare the two reports.

Rate and transport (cp / bench / get)

Flag	Default	Meaning
`-l` / `--max-rate`	25g	Highest rate to try (k/m/g suffixes). Required for `--policy fixed`. Without a license file, free copies on one machine share 1 Gbit/s in total, and the rate shows `(free limit)` when that is what slows a copy.
`--license`	—	License file. Raises the 1 Gbit/s free limit to the license's speed. `--license` is the same flag. There is still no limit on copies at once.
`-m` / `--min-rate`	0	Lowest rate for auto / background policies.
`--start-rate`	from history	First rate when the transfer starts.
`--policy`	auto	`auto`, `fixed`, or `background`.
`--transport`	auto	`auto` (UDP→TCP→SSH), `udp`, `tcp`, or `ssh`.
`--lanes`	4	Parallel UDP sessions on consecutive ports.
`--streams`	8	Parallel streams for TCP or SSH carry.
`--port`	47700	Remote data port (UDP and TCP fallback).
`-q` / `--quiet`	off	No progress line.
`--json`	—	Write a summary JSON file.
`--log`	—	Rate-control samples (JSON lines every 100 ms).

SSH options

Flag	Meaning
`-P` / `--ssh-port`	SSH port.
`-i` / `--identity` / `--ssh-key`	Private key file, as for `ssh -i`.
`--password-env`	Read the SSH password from this environment variable instead of asking.
`--password-file`	Read the SSH password from the first line of this file instead of asking. Only you may be able to read the file.
`-o` / `--ssh-option`	Extra `ssh -o` option (repeatable).
`--ssh`	SSH program (default `ssh`).
`--remote-path`	Path of `farwing` on the remote host.
`--udp-host`	Data host/address if it differs from the SSH host.

Listener options

Flag	Meaning
`--key-file`	The key file the listener was started with (see `farwing keygen`). Needed for a `farwing://` path.
`--connect`	`farwing bench` only: test against a listener at `host:port`. The same as `farwing bench farwing://host:port`.

farwing listen itself takes --bind ADDRESS:PORT (default 0.0.0.0:47700), --key-file, --dir FOLDER (the folder it serves), --sink (discard data, for speed tests), --once (exit after one copy) and --lanes.

Examples

farwing cp big.iso user@host:/data/
farwing cp photos/ user@host:/data/
farwing cp a.txt notes/ user@host:/data/
farwing cp user@host:/data/big.iso .
farwing cp -i ~/.ssh/lab_ed25519 big.iso user@host:/data/
farwing cp --key-file lab.key big.iso farwing://host:47710/
farwing cp --key-file lab.key farwing://host:47710/big.iso .
farwing cp --ticket "$TICKET" ./payload.bin
farwing cp --ticket "$TICKET" .
farwing cp --ticket "$TICKET" notes.txt cuts/ final.mov
farwing get https://files.example.com/r/TOKEN ./delivery
farwing get https://files.example.com/r/TOKEN --passcode CODE
farwing bench user@host --size 5G
farwing doctor
farwing doctor --path /data --size 2G
farwing doctor user@host
farwing daemon --port 47700