BluetoothConnector and the CLI for connecting AirPods from a Mac

Why the tool exists

The README explains the origin plainly. The author made it to easily connect BeatsX earbuds, and expected the W1 chip to make the switch from an iPhone to a Mac automatic, but that is apparently not the case yet. The author also notes there is probably a program that already does this, but did not find it.

That origin story tells you what the tool is and is not. It is a narrow utility that solves a narrow annoyance: getting a pair of earbuds to switch to the Mac without opening the Bluetooth menu and clicking. It is not a Bluetooth manager, it does not enumerate or configure devices, and it is not a general-purpose tool for anything else.

The description puts it as a simple macOS CLI to connect/disconnect a Bluetooth device, useful for AirPods or other Bluetooth headphones. The language is Swift, the package is distributed through Swift Package Manager, and it is published as a Swift package with a Package.swift, a Sources/ directory and a Tests/ directory at the root of the repository. There is a Package.resolved alongside it and a .spi.yml, which is the configuration file for the Swift Package Index.

The audience is a Mac user with Bluetooth headphones, and specifically one who wants a scriptable, bindable command rather than menu-clicking. The topic list names the ecosystem it targets, with macos-cli, shortcut, automator-workflow, swift-package and swift-package-manager among the tags, and airpods, beats and beatsx naming the hardware it was built around.

The licence is MIT, with a LICENSE file at the repository root, so there is no obstacle to using it in your own scripts.

Installing it, three ways

There are three documented installation routes, and they cover the different cases in which you might want this tool.

Homebrew is the first and simplest:

brew install bluetoothconnector

Mint is the second, for people who use that package manager:

mint install lapfelix/BluetoothConnector

And the manual route builds from source with the Swift toolchain:

swift package update
swift build -c release
mv .build/release/BluetoothConnector /usr/local/bin/BluetoothConnector

The manual route is worth reading closely, because the last step is a move into /usr/local/bin, and that directory is not on the default PATH of every macOS setup, particularly on Apple silicon where Homebrew installs to /opt/homebrew. The Automator instructions later in the README deal with exactly this, since the workflow looks for the binary in /usr/local/bin.

There is also a pre-built option. The README links the releases page for a compiled version, and warns about a specific failure: if you have issues running the compiled binary with a permission denied error, try running chmod +x /path/to/BluetoothConnector in Terminal. That is the quarantine attribute that macOS puts on downloaded executables biting a user who does not expect it, and it is a one-command fix.

The release history is thin. The tagged versions are 1.2.0 from 2019-01-27, 2.0.0 from 2020-05-03 and 2.1.0 from 2023-10-06, and the repository is not archived with a last push on 2026-07-19. So the tool is small and stable rather than actively churning.

The command surface: one identifier, a few verbs

The whole interface is a MAC address and a set of flags, and the documentation is built around that.

The address is the one thing you must supply. The README says to replace 00-00-00-00-00-00 with your device's MAC address, and gives two ways to find it: alt-clicking the Bluetooth menu icon, or running BluetoothConnector without any arguments. That second route is the useful one, since it means the tool can tell you what to pass rather than making you read it off a menu.

The first form is a toggle, which connects or disconnects depending on the current state, with a notification flag:

BluetoothConnector 00-00-00-00-00-00 --notify

The explicit forms are --connect and --disconnect, each of which has a short alias, -c and -d:

BluetoothConnector --connect 00-00-00-00-00-00 --notify
BluetoothConnector -c 00-00-00-00-00-00 --notify

BluetoothConnector --disconnect 00-00-00-00-00-00
BluetoothConnector -d 00-00-00-00-00-00

The --notify flag is what makes the tool usable from a script without a terminal in front of you. The README describes it as sending a notification saying what it did, connect or disconnect, if the action succeeded, or an error description if something went wrong. There is a screenshot of the Notification Center entry to show the shape of it.

One refinement the author suggests: to reduce Notification Center pollution, turn off Show in Notification Center for the Script Editor app in the Notifications system preferences. That detail reveals something about how the notifications are delivered, since the Script Editor application is what appears as the source.

The API is small enough to learn in a minute, and small enough that you can wrap it in a shell alias, a script, or the workflow described next.

The Automator workflow, which is the real feature

The README is explicit that the workflow is how the author uses the tool, and it is a bundle of the repository rather than something you install from a package manager.

The author included an Automator workflow service that calls BluetoothConnector from /usr/local/bin to make it easier to run with a keyboard workflow. And there is a specific reason a package install is not enough: to use the workflow you will need a copy of this repo, a brew install is not enough.

The steps are: clone the repo; in the root directory there is a file named Connect Bluetooth Device.workflow, click on it and accept the install prompt; in settings, under Keyboard, Shortcuts, Services and General, bind the Bluetooth Connect service to whatever shortcut you want; then set the MAC address, since the workflow can be found in /Users/[username]/Library/Services, open it and set your address; and finally create a link, because the workflow calls /usr/local/bin.

That last step is the fiddly one. The README says to head over to usr/local/bin and create a link to your brew install, something like:

The command the README suggests is a sudo ln -s pointing at a path under /opt/homebrew/Cellar/bluetoothconnector/2.1.0/bin/BluetoothConnector.

The symlink target is versioned, with 2.1.0 in the Cellar path, which means the link breaks when Homebrew upgrades the formula to a new version. That is a maintenance detail you inherit, and it is the kind of thing the author clearly has run into, which is why the link is described as a separate step rather than being automatic.

The payoff is the last line of that section: test out the keyboard shortcut. You will need to grant permissions the first time you run the workflow, since an Automation service that drives a binary has to be allowed to do so.

This is the part of the project worth stealing if you write your own macOS CLI: the tool is only useful if something can invoke it, and macOS gives you a first-class way to bind a script to a key.

Limitations, and the honest scope of the tool

Three limits are worth stating before you plan to rely on it.

The first is that the identifier is a MAC address, not a device name. Every invocation needs a fixed hardware address, which means the tool cannot be used with a device you have not already looked up, and it cannot disambiguate between two identical products. The README's answer is to run the tool with no arguments and read the address from the output, which is a workable flow for a device you own, and a clumsy one for a device you have to support for someone else.

The second is that the tool sits above macOS's Bluetooth stack rather than inside it. It issues the connect request through the system, which means the outcome depends on what the system allows: whether the device is paired, whether another device currently holds the connection, and whether the audio route is already taken. The author's own framing, that the W1 chip was supposed to make the handover automatic and does not, is an admission that the underlying experience is not fully in the software's control. The --notify flag exists precisely because the result is not always what you asked for, and you need to know.

The third is platform. This is a macOS command line tool, written in Swift and built with Swift Package Manager, and the topic list confirms the scope with macos and macos-cli. There is no Linux or Windows version here, and the macOS and Windows equivalents of the broader WhiteSur style tooling live in other projects.

The related point about the repository's wider family is worth noting too, because the manual symlink instruction points at it. The path in the README is a Homebrew Cellar path, which is the /opt/homebrew prefix used by the WhiteSur project family for macOS tooling, so this tool is one member of a wider set of macOS appearance and behaviour customisations rather than a standalone utility.

Editorial conclusion

BluetoothConnector is a good fit for a Mac user who switches between a phone and a laptop and wants one keystroke to move audio, because it does one small thing from the terminal and ships an Automator workflow to put it on a shortcut. It is a poor fit if you want a general Bluetooth manager, since the tool connects and disconnects a device and does not list or configure the adapter, and a poor fit if you do not know the MAC address of the target, since that is the only identifier the command takes. Before adopting, confirm your Bluetooth hardware is macOS-managed rather than handled by a vendor utility, and note that the latest tagged release is 2.1.0 from 2023-10-06 while the last push was on 2026-07-19, so treat the compiled download as the thing to verify.

Frequently asked questions

Official sources

1. Issues
2. lapfelix/BluetoothConnector on GitHub
3. License: MIT
4. README
5. Releases