Send files to another Mac from the terminal with homedrop
By Flavio
Pair two Macs, set up groups and send files or folders to your other Mac from the terminal or a script with homedrop, the command that comes with Home Drop.
You’re in the terminal, and the file you need is on the wrong Mac. Maybe it’s a build you want to try on the laptop, a folder of exports for your partner’s Mac, or a PDF a script just generated. AirDrop wants a click. scp wants Remote Login turned on, an account name and a password, and I covered that route in how to download a file from a server using the terminal.
Home Drop is a Mac app that sends files straight to the other Macs at home over your local network, encrypted, with no accounts and no servers. It comes with a command called homedrop that does everything the window does: pair, group, send, receive, and show the history.
By the end of this page you’ll have homedrop on your PATH, two Macs paired from the terminal, a group that decides who gets what, and a one-line send you can put in a script or hand to a coding agent. If you’d rather drag files onto a window, Send photos and files between your Macs without AirDrop covers the app side.
What you need
Home Drop needs macOS 14 or later, and it runs on Apple silicon and Intel Macs. Install it on every Mac that sends or receives.
After you pay, download Home-Drop-1.3.0.zip from your Polar receipt, unzip it, and move Home Drop.app to Applications. The download is signed with my Developer ID and notarized by Apple.
The homedrop command is inside the app bundle, at Home Drop.app/Contents/Helpers/homedrop. It shares its state with the app, so a Mac you pair in the terminal shows up in the window and the other way around.
Both Macs have to be on the same network and awake. The first time Home Drop looks for other Macs, macOS asks for the Local Network permission. Allow it on both Macs. Without it, Bonjour can’t find the other Mac and pairing never starts. If you clicked the wrong button, this guide to the Local Network dialog shows how to change your answer.
The preflight check comes in the next section: once the command is linked, homedrop --version should print a version number.
Names in the examples below, like Anna’s MacBook Air, the Trip folder and the group names, are examples. The outputs are from real runs.
Put homedrop on your PATH
The command lives deep inside the app bundle, and typing that full path every time gets old fast. A script or a coding agent that can’t find it fails with command not found. A symlink in a folder that’s already on your PATH fixes both. Because it points into the app, it keeps working when Home Drop updates itself: the new version replaces the app, and the link still lands on the new homedrop. The docs use ~/.local/bin, which many setups already have on the PATH.
mkdir -p ~/.local/bin
ln -s "/Applications/Home Drop.app/Contents/Helpers/homedrop" ~/.local/bin/homedrop
homedrop --version
homedrop 1.3.0
If you get command not found instead, ~/.local/bin isn’t on your PATH yet. Add it in your shell’s config file and open a new terminal window.
Next, check who this Mac is in Home Drop. Every Mac makes its own key the first time it runs, and whoami shows the name other Macs see, a device id, a short key fingerprint, and the folder where the state lives:
homedrop whoami
MacBook Pro
id 2EA45047-EB29-4D2B-9C17-4B82282636D1
key BC9F·F5EB
state /tmp/hd-tut.C6Vn/a
On your Mac the state line points to ~/Library/Application Support/Home Drop. Mine shows a temporary folder because I ran these commands with --state, which I’ll come back to later.
A name like “MacBook Pro” is useless when both Macs are MacBook Pros. Rename it:
homedrop name "Studio Mac mini"
This Mac is now "Studio Mac mini" in Home Drop. Paired Macs see the new name next time they pair.
Do this before you pair. As the message says, Macs you already paired keep the old name until you pair again.
Pair the two Macs from the terminal
Pairing is how the two Macs learn each other’s keys. Until they do, neither Mac will accept a connection from the other, so send has nobody to send to. It works with a 6-digit code. One Mac shows it, and you type it on the other. Home Drop mixes the code into a fresh key exchange, so only a Mac that knows the code can swap keys. Every transfer after that derives new AES-GCM keys from both Macs’ paired keys plus another fresh exchange. A Mac that isn’t paired can’t connect at all.
On the first Mac, run pair with no arguments. It prints the code and waits:
homedrop pair
It prints the pairing code and the exact command to run on the other Mac, with this Mac’s name filled in. It also prints the port it’s listening on, which matters if Bonjour can’t find it. It waits up to 5 minutes. If nobody pairs in that time, it stops with Nobody paired in 5 minutes.
On the second Mac, run pair with the first Mac’s name and the code:
homedrop pair "Studio Mac mini" 482913
When it works, both sides print a Paired with … line with the other Mac’s name and key fingerprint. You can check the fingerprint against what homedrop whoami shows on the other Mac.
The name doesn’t need to be exact. homedrop looks for a Mac on the network whose name contains what you typed, ignoring case, so "studio" is enough. If Bonjour doesn’t find it, you get Couldn't find "studio" on the network. Use host:port to connect directly. Then use the first Mac’s IP address and the port it printed, like homedrop pair 192.168.1.20:52000 482913.
You can also pair with Pair a Mac (⌘P) in the app on one side and homedrop pair on the other.
Choose who gets the files with groups
Without a target, send sends to the default group. That’s convenient, until the default group is the wrong set of Macs and the folder you meant for your own laptop lands on someone else’s. A group is a set of paired Macs, like “Family” or “Me” for your own Macs. Each group has its own stream of what was sent and received, so history can show one group at a time. A Mac you pair from the terminal joins the default group automatically, like in the app. It’s worth looking at the groups once, right after pairing.
homedrop groups
★ Family (no Macs)
Me (no Macs)
A fresh install has these two groups. The star marks the default one, and each line lists the paired Macs in that group, or (no Macs).
Example 2: a group for the Macs in the studio. Say you want builds to go to two office Macs, and photos to keep going to Family. Create a group with the Macs in it and make it the default, then move it back later:
homedrop groups add Studio "Anna's MacBook Air" --default
homedrop groups rename Studio Office
homedrop groups default Family
Added Studio.
Renamed Studio to Office.
Family is the default group.
You can name Macs when you create the group, or add and remove them one at a time with groups add-peer <group> <mac> and groups remove-peer <group> <mac>. If a group name is already taken, groups add stops with There's already a group called "Family".
For a script, --json gives you the same list with ids and an isDefault field:
homedrop groups --json
[
{
"id" : "E6B883DE-8038-4300-938E-4407363A80CE",
"isDefault" : true,
"name" : "Family",
"peers" : [
]
},
{
"id" : "EAFD3D28-C3AB-4E9A-90B8-E34E4B3F0517",
"isDefault" : false,
"name" : "Me",
"peers" : [
]
}
]
groups remove <name> deletes a group right away, with no confirmation step. It removes the group, not the Macs in it: they stay paired.
Send files and folders
This is the command you’ll run every day. send takes one or more files or folders, finds each Mac in the target group on the network, and copies the originals over a direct connection. Folders keep their structure on the other side, and hidden files inside them, like .DS_Store, are skipped. A photo and a .mov with the same name side by side travel as the two halves of a Live Photo. The thing to know before you script it: the app keeps a send waiting when a Mac is offline, but send gives each Mac a few seconds to show up and then reports it as not online.
Example 1: send a trip folder to your partner’s Mac. You paired with Anna’s MacBook Air, and it’s in Family, the default group. One line sends the whole folder:
homedrop send ~/Pictures/Trip
It first prints a line with the number of files, the total size, and the Macs it’s sending to. While the copy runs, it prints progress for each Mac with a percentage, the bytes done and the speed. When a Mac has everything, you get Sent to Anna's MacBook Air in … with the seconds it took and the average MB/s.
To pick the target, use --group for a group or --peer for one paired Mac. --peer matches names the same forgiving way as pair:
homedrop send ~/Desktop/report.pdf --group Me
homedrop send ~/Desktop/build.zip ~/Desktop/notes.md --peer anna
If a part of the name matches two Macs, send refuses and lists both, ending with Be more specific.
When Bonjour can’t see the other Mac, --to host:port connects to an address directly, like --to 192.168.1.20:52000. The Mac at that address still has to be paired with yours. If you leave out the port, you get --to needs host:port, like 192.168.1.20:52000.
Sending the same folder twice sends it twice. The receiving side never overwrites a file: if report.pdf is already in the folder, the new copy is saved as report 2.pdf. Undoing a send means deleting the copies on the other Mac.
send exits with status 0 only when every Mac got the files. If one of three Macs was asleep, it tells you which one, ends with 1 of 3 didn't get the files., and exits with 1, so a script can retry later.
Receive files without the app
The Mac on the other end needs something listening. Usually that’s the Home Drop app, which saves to ~/Downloads/Home Drop, or a Photos album if you picked that in Settings. On a Mac you only reach over SSH, homedrop receive does the listening instead. The help text says not to run it while the Home Drop app is open, so quit the app on that Mac first.
homedrop receive --to ~/Shared/Inbox --once
It prints the port it’s waiting on and the folder files go to. Each transfer prints who is sending and how many files, then a Saved … line with the count and the speed when it’s done. --once stops after the first transfer, which suits a script that waits for one delivery. Without it, receive keeps waiting until you press Ctrl-C. --port N picks the port, so you know what to pass to --to on the sending Mac. Like the app, it keeps the sender’s file dates and never overwrites what’s already in the folder.
Check what went out with history
A send that ran in a script at night leaves no window behind. history is how you find out whether it worked. Every send and receive gets an entry with the group, who sent it to whom, the number of files, the total size and a status. The app and the command share this history, so a drop on the window shows up here too. It keeps the last 500 entries. By default history shows the newest 20; --limit changes that and --group filters to one group’s stream.
homedrop history --group Family --limit 5
On a Mac that hasn’t sent anything yet, it says so:
Nothing sent or received yet.
Once there’s something, each line has the date and time, the group in brackets, You → Anna's MacBook Air or Anna's MacBook Air → you, the file count and size, and the status. Add --json for the full entries, with file names, paths and per-Mac status, which is what a script should parse.
Hand it to a coding agent
A coding agent on your Mac can run homedrop like any other command, so “send the release build to the laptop when the tests pass” becomes one step at the end of its task. A wrong guess at a flag sends files to the wrong group. capabilities prints what the tool can do with an example command for each task, plus the release history. It reads nothing from the network, so it’s safe to run any time:
homedrop capabilities
homedrop 1.3.0
Sends photos and files straight to other Macs on the home network with Home Drop, encrypted, with no iCloud.
What it can do:
Send photos, videos or folders to the default group of Macs
$ homedrop send ~/Pictures/Trip/*.HEIC
Send files to a specific group or one paired Mac
$ homedrop send ~/Desktop/report.pdf --group Me
Pair this Mac with another one using a 6-digit code
$ homedrop pair "Anna's MacBook Air" 482913
Show a pairing code and wait for another Mac to pair
$ homedrop pair
List paired Macs and the ones online nearby
$ homedrop peers --json
Create a group of Macs and make it the default
$ homedrop groups add Family "Anna's MacBook Air" --default
Receive files into a folder without the app running
$ homedrop receive --to ~/Downloads/Home\ Drop
Show what was sent and received in a group's stream
$ homedrop history --group Family
The output continues with the changelog. capabilities --json gives the same thing as JSON. In your agent instructions, I’d name the target explicitly, like “send with --group Me”, so the agent never relies on whatever the default group is that day.
To try commands without touching your real pairings, pass --state with another folder, or set HOMEDROP_STATE. That’s how I ran the examples on this page.
Example 3: the default group is empty. After reorganizing groups, the default one can end up with no Macs. The send fails before anything leaves:
homedrop send ~/Desktop/menu.pdf
homedrop: Family has no Macs. Add one with homedrop groups add-peer.
The fix is in the message. Add the Mac to the group, or send to it directly:
homedrop groups add-peer Family "Anna's MacBook Air"
homedrop send ~/Desktop/menu.pdf --peer "Anna's MacBook Air"
To remove a Mac entirely, homedrop peers remove "Anna's MacBook Air" forgets it and takes it out of every group. There’s no confirmation, and it only affects this Mac: the other Mac keeps its pairing until you forget it there too. If you sell or wipe a Mac, forget it on every Mac you keep.
If something looks wrong
- If you get
homedrop: No paired Mac called "Anna". Run homedrop peers., the name doesn’t match any paired Mac. Runhomedrop peersto see the names, and pair first if the list is empty. - If you get
No group called "Nope". Run homedrop groups., check the spelling withhomedrop groups. Case doesn’t matter, but the whole name has to match. - If
sendsaysCouldn't send to Anna's MacBook Air: Anna's MacBook Air isn't online, that Mac is asleep, off the network, or has no Home Drop listening. Wake it, open the app or starthomedrop receive, and send again. - If pairing says
Couldn't find "studio" on the network. Use host:port to connect directly., check that both Macs allowed the Local Network permission, then pair with the IP address and the port the waiting Mac printed. - If
pairsaysUsage: homedrop pair <mac name or host:port> <6-digit code>, the code wasn’t 6 digits. Copy it again from the other Mac. - If you get
--to needs host:port, like 192.168.1.20:52000, you left out the port.homedrop receive --porton the other Mac fixes the port so you know it in advance. - If
sendsaysThe file “menu.pdf” doesn’t exist., the path is wrong. Quote paths with spaces, or tab-complete them. - If a received file is called
report 2.pdf, nothing broke. A file with that name was already in the folder, and Home Drop never overwrites.
Get Home Drop
Send photos and files straight to your other Macs over the local network. Pair once with a 6-digit code, no accounts and no servers. Includes a native Mac app, CLI and full MIT source.
See Home Drop → · Read the docs · $20. See the app page for tax details, with full source code.
Want me to talk about your product? You can sponsor this site.