TETHER(1)

📦 version 0.2.37, in nixpkgs unstable

💖 NAME 💖

Ok so this is tether, aka TETHER(1), filed under User Commands — the Wayland companion CLI for iPhone integration. Slay. ✨

✨ SYNOPSIS ✨

tether [OPTIONS]
tether COMMAND [ARGUMENTS]

🦋 DESCRIPTION 🦋

tether is a command-line interface for communicating with the Tether daemon (tetherd). It allows for clipboard synchronization, file transfers, and device management between a Linux Wayland desktop and an iOS device. 💅

Most options also have a subcommand form, so tether devices and tether --list-devices are literally the same thing. See COMMANDS below. 🫶

🎀 OPTIONS 🎀

Bestie, here is the whole flag lineup — no skips, no cap:

  • -h, --help — Show help message and exit. Your classic “what do I do” button.
  • -v, --version — Print the tether version and exit.
  • -g, --get-clipboard — Retrieve the current Wayland clipboard text from the daemon.
  • -s, --set-clipboard [STRING] — Copy the provided string — or stdin if the string is omitted — to the local Wayland clipboard.
  • -f, --send-file FILE — Send a file to the currently connected device.
  • -n, --native-host — Start the browser Native Messaging Host proxy loop (used by browser extensions).
  • -d, --discover — Scan the local network for tetherd instances via mDNS.
  • --host IP — Connect over TCP to the daemon at the specified IP address instead of using the local UNIX socket.
  • --port NUM — Connect over TCP port (default: 5134).
  • --timeout MS — Discovery scan duration in milliseconds (default: 3000).
  • --list-devices — List all paired connection devices and their fingerprints.
  • --status — Print what the daemon is doing: version, clipboard and mDNS state, how many devices are paired, how many pairing requests wait, which peers are connected, and the files most recently received.
  • --pending — List the Wi-Fi pairing requests waiting to be accepted, with the fingerprint --accept takes. On a machine with no GTK app to show the prompt, this is how a request is seen.
  • --accept FINGERPRINT — Accept a pending pairing request locally for the specified device fingerprint.
  • --pair — Send a pairing request over TCP to the daemon.
  • --forget FINGERPRINT — Remove a Wi-Fi pairing and close any session it holds. The daemon reconnects to paired peers on its own, so a peer stays unwanted only once both ends have forgotten it. 👀
  • --install-extension-host — Install the browser and mail extension’s native messaging manifests into this user’s Firefox, Thunderbird, and Chromium directories, pointing at a wrapper in ~/.local/bin. Needed only for a portable build such as the AppImage; the distro packages install the manifests system-wide.
  • --install-btclass-unit — Write tether-btclass@.service to /etc/systemd/system. Needs root, and never enables it. Needed only for a portable build such as the AppImage; the distro packages install the unit themselves. See --bt-setup.
  • --install-service — Write tetherd.service into ~/.config/systemd/user and print the commands that enable it. Never enables or starts anything. Needed only for a portable build; the distro packages install the unit system-wide. Without systemd it writes nothing.
  • --uninstall-service — Remove the tetherd.service unit this user installed.

🌈 COMMANDS 🌈

Each of these is the option named beside it, so nothing behaves differently for having been typed as a word. A first argument that is not one of these, or that starts with a dash, is left for the option parser. 🫡

  • status, devices, pending — --status, --list-devices, --pending
  • accept FINGERPRINT, forget FINGERPRINT, pair — --accept, --forget, --pair
  • discover, send FILE, copy [STRING], paste — --discover, --send-file, --set-clipboard, --get-clipboard
  • service, version, help — --install-service, --version, --help
  • bt NAME [ARGUMENTS] — The --bt-NAME option, so tether bt pair AA:BB:CC:DD:EE:FF is tether --bt-pair AA:BB:CC:DD:EE:FF.

💜 BLUETOOTH OPTIONS 💜

Bluetooth carries iPhone messages (MAP), contacts (PBAP), and notification mirroring (ANCS). It is independent of the Wi-Fi pairing above. 🦋

  • --bt-setup — Show the one-time system setup Bluetooth still needs, with the command for each step. Nothing is applied: the steps change how the machine behaves over Bluetooth outside Tether, so running them is left to the user. One step enables tether-btclass@ADAPTER.service, which is installed by the package but never enabled for you. A portable build has no unit on disk, so the printed command writes it out first: with --install-btclass-unit on the AppImage, and as a here-document elsewhere.
  • --bt-status — Show Bluetooth adapter capability and delivery mode.
  • --bt-devices — List Bluetooth devices known to BlueZ.
  • --bt-connection — Show Bluetooth link and profile connection state.
  • --bt-airpods — Show AirPods battery, for each bud and the case, and the current listening mode.
  • --bt-airpods-enable on|off — Manage AirPods from Tether at all: battery, listening mode, in-ear pausing and handoff. Off by default, because the AAP channel takes one program per computer and opening it takes the buds away from any other AirPods program.
  • --bt-airpods-mode off|anc|transparency|adaptive — Set the AirPods listening mode. The buds decline a mode they are not configured for without reporting an error, so check the result with --bt-airpods.
  • --bt-airpods-pause never|one-removed|both-removed — Pause whatever is playing on this computer when an AirPod is removed, and start it again when the buds go back in. Off by default. Only playback Tether paused is resumed.
  • --bt-airpods-handoff on|off — Hand the AirPods to the iPhone when it has a call and take them back afterwards. Off by default. Requires call control (--bt-calls-enable on).
  • --bt-pair ADDRESS — Pair with an iPhone over Bluetooth.
  • --bt-unpair ADDRESS — Remove a Bluetooth bond.
  • --bt-solicit — Re-advertise for ANCS so the iPhone shows its permission toggles again.
  • --bt-threads — List iPhone message conversations.
  • --bt-messages THREAD — Show messages in one conversation.
  • --bt-send THREAD TEXT — Reply in one conversation.
  • --bt-contacts [QUERY] — List iPhone contacts, or search them by name, number or email address. Prints each contact’s name followed by its addresses, one per line, in the same tel:/email: form --bt-send takes as its conversation.
  • --bt-retention encrypted|plaintext|none — How message history and the contact cache are kept on disk. encrypted, the default, seals them with a key from the desktop keyring, falling back to a 0600 key file on a host with no secret service. plaintext keeps the readable files earlier versions wrote. none deletes what is already stored and retains nothing further. Heads-up: losing the keyring entry loses the retained history — there is no escrow and no plaintext copy is left behind. 😭
  • --bt-notifications — List mirrored iPhone notifications.
  • --bt-ancs on|off — Turn notification mirroring on or off.
  • --bt-ancs-content on|off — Mirror notification titles and bodies, not just the app.
  • --bt-calls — List calls on the iPhone: what is ringing, dialing, or connected.
  • --bt-call number — Place a call from the iPhone. A leading + and digits are kept; spaces, dashes, dots and parentheses are dropped and anything else is refused.
  • --bt-answer — Answer the ringing call.
  • --bt-hangup — End every call.
  • --bt-calls-enable on|off — Turn call control on or off. Off by default. Calls run over whichever stack holds the hands-free profile: BlueZ’s own, which needs bluetoothd --experimental — the same flag notification mirroring requires — and carries no audio, or PipeWire’s, which carries the call audio as well. Neither is installed by Tether and call control is unavailable, not broken, when there is no stack holding the profile. See docs/BLUETOOTH.md.
  • --bt-call-audio on|off — Play call audio on this computer, or leave it on the iPhone. Only PipeWire carries the voice link, so this reports a refusal when BlueZ holds the profile. off gates the next voice link rather than moving a call already in progress.
  • --bt-adapter hciN|auto — Choose which Bluetooth controller to use, by hciN or by address. Defaults to auto, the first powered controller, which is the wrong one on a machine with more than one. --bt-status marks the controller in use.
  • --bt-diagnostics — Print a redacted Bluetooth report for a bug report.

💅 EXAMPLES 💅

Retrieve clipboard:

tether -g

Copy text to clipboard:

echo "Hello from Linux" | tether -s

Discover other Tether instances:

tether --discover

Send a file:

tether -f document.pdf

See what Bluetooth still needs before pairing an iPhone:

tether --bt-setup

The same things, as subcommands:

tether send document.pdf

tether bt setup

🧚 FILES 🧚

  • /usr/lib/systemd/user/tetherd.service — Starts tetherd for one user. Installed by the distro packages but never enabled; a portable build writes its own copy to ~/.config/systemd/user with --install-service. The daemon does not need a Wayland session: without one it runs with clipboard sync off.
  • /usr/lib/systemd/system/tether-btclass@.service — Sets the Bluetooth adapter’s Class of Device to A/V Hands-Free, which iOS requires before it will offer its Messages and Contacts permissions. Installed by the distro packages but never enabled; a portable build writes it to /etc/systemd/system instead. See --bt-setup.

🌟 SEE ALSO 🌟

tetherd(8), tether-gtk(1), systemd.unit(5)

🎀 That’s the whole page, bestie! Source/version/date vibes: Tether 0.2.37, January 1980, manual page TETHER(1). Bye and slay 💅✨
📦 where this page comes from