Start here
mux copies and syncs files between folders, web addresses and other machines. This page goes through the three things most people use it for.
Install
On macOS or Linux, run this in a terminal:
curl -fsSL https://mux.yuvich.com/install.sh | sh
It puts mux in ~/.local/bin. With Homebrew, run
brew install yuvichh/tap/mux. On Windows, download
mux.exe
and put it in a folder on your PATH.
Check that it runs:
$ mux --version
mux 0.3.0
Send a folder to another machine
On the machine that has the folder, offer it. Leave the command running.
$ mux cp ./photos peer:
seeding photos (23.17 MiB, 28 chunks)
mux://c11f2fe5…
The last line is a ticket. Send the whole line to whoever is to get the folder: in a chat, by mail, any way you like. Anyone who has the ticket can fetch the folder while the command runs.
On the other machine, copy from the ticket into a folder. Put the ticket in quotes: it holds characters that a shell reads as its own.
$ mux cp 'mux://c11f2fe5…' ./downloads/
saved ./downloads/photos (23.17 MiB, verified)
- The two machines do not need to be on one network. They connect directly where their routers allow it, and through an encrypted relay where they do not.
- If the copy is cut off, run the same command again. It checks what is there and fetches the rest.
- When the other machine has the folder, stop the first command with Ctrl-C.
Sync a folder
mux sync makes a folder match its source. It fetches only what changed.
Look at what it would do first:
$ mux sync 'mux://8a41d0c7…' ./backup/photos --delete --dry-run
touch .
touch 2026
add 2026/IMG_107.jpg
remove notes.txt
replace trip.mov
would add 1, replace 1, touch 2 and remove 1, and kept 6 (10.59 MiB to bring)
Then run it without --dry-run:
$ mux sync 'mux://8a41d0c7…' ./backup/photos --delete
added 1, replaced 1, touched 2 and removed 1, and kept 6 (3.59 MiB fetched, 7.00 MiB reused)
what was replaced or removed is in ./backup/photos/.mux-trash/1795289743.047642000
- A ticket names the folder as it was when it was offered. To bring later changes across, offer the folder again and sync from the new ticket.
- Nothing is removed without
--delete. - What is replaced or removed is moved to
.mux-trashinside the folder, so a mistake can be put right. - The source can also be another folder on the same machine:
mux sync ./photos /mnt/backup/photos.
Download from the web
Give mux cp a web address and a folder:
$ mux cp https://github.com/yuvichh/mux/releases/download/v0.3.0/mux-x86_64-linux.tar.gz ./downloads/
saved ./downloads/mux-x86_64-linux.tar.gz (5.86 MiB, consistent)
It fetches the file in several parts at once and carries on after a break.
If you know the file's digest, give it with --hash, and the copy is
checked against it:
mux cp https://example.org/big.iso ./downloads/ --hash sha256:<64 hex characters>
Use it from a script
Every command takes --json and then writes one JSON object on each line
of standard output. The exit code says what happened:
| Code | Meaning | Run it again? |
|---|---|---|
| 0 | Done | |
| 2 | The command is written wrong | No |
| 3 | Nothing is at the source | No |
| 4 | The source could not be reached, or stopped sending | Yes |
| 5 | The source changed while it was read | Yes |
| 6 | What arrived is not what was asked for | No |
Commands has every command, flag and JSON line.