Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Go Report Card



bluetuith is a TUI-based bluetooth connection manager, which can interact with bluetooth adapters and devices. It aims to be a replacement to most bluetooth managers, like blueman.

This is only available on Linux.

This project is currently in the alpha stage.


  • Transfer and receive files via OBEX.
  • Perform pairing with authentication.
  • Connect to/disconnect from different devices.
  • Interact with bluetooth adapters, toggle power and discovery states
  • Connect to or manage Bluetooth based networking/tethering (PANU/DUN)
  • Remotely control media playback on the connected device
  • Mouse support


  • Bluez
  • DBus
  • NetworkManager (optional, required for PANU)
  • ModemManager (optional, required for DUN)
  • PulseAudio (optional, required to manage device audio profiles)


If the go compiler is present in your system, you can install it via the following command: go install

Or you can navigate to the releases section and download a binary that matches your architecture.

It is also available in the AUR as bluetuith-bin.


bluetuith [<flags>]

  --adapter <adapter>          Specify an adapter to use. (For example, hci0)
  --gsm-apn <apn>              Specify GSM APN to connect to. (Required for DUN)
  --gsm-number <number>        Specify GSM number to dial. (Required for DUN)
  --list-adapters              List available adapters.
  --receive-dir <dir>          Specify a directory to store received files.
  --set-theme <theme>          Specify a theme
  --set-theme-config <config>  Specify a comma-separated list of modifier-color pairs.
  • To use DUN-based networking, it is required to specify the gsm-number option. The gsm-apn field is optional.

  • If the receive-dir option is not specified, received files will be stored in $HOME/bluetuith.

  • For more information on how to use the set-theme and set-theme-config options, navigate to the Themes wiki page.


bluetuith should generally work out-of-the-box, with no required configurations.

If persistent configuration for certain settings is required, a config file can be used.
The config file is automatically created on startup, and its location can be viewed on invoking bluetuith --help.

Configuration properties can be in the form of a simple name=valueor name value pair.

For example:



Device Screen

Operation Keybinding
Open the menu Ctrl+m
Navigate between menus Tab
Navigate between devices/options Up/Down
Toggle adapter power state o
Toggle discoverable state S
Toggle pairable state P
Toggle scan (discovery state) s
Change adapter a
Send files f
Connect to network n
Progress view v
Connect to selected device c
Pair with selected device p
Trust selected device t
Show media player m
Hide media player M
Show device information i
Remove device from adapter d
Cancel operation Ctrl+x
Quit q

File Picker

Operation Keybinding
Navigate between directory entries Up/Down
Enter a directory Right
Go back one directory Left
Select one file Space
Invert file selection a
Select all files A
Refresh current directory Ctrl + r
Toggle hidden files Ctrl+h
Confirm file(s) selection Ctrl+s
Exit Escape

Progress View

Operation Keybinding
Navigate between transfers Up/Down
Suspend transfer z
Resume transfer g
Cancel transfer x
Exit Escape

Media Player

Operation Keybinding
Toggle play/pause Space
Next >
Previous <
Rewind Left
Fast forward Right
Stop ]

Planned features

  • OBEX file transfer.
  • Display the device type and icon.
  • Display range (RSSI) of the connected device.

Additional notes

  • Ensure that the bluetooth service is up and running, and it is visible to DBus before launching the application. With systemd you can find out the status using the following command: systemctl status bluetooth.service.
  • Only one transfer (either of send or receive) can happen on an adapter. Attempts to start another transfer while a transfer is already running (for example, trying to send files to a device when a transfer is already in progress) will be silently ignored.


Special thanks to:

  • vishen, for the bluez implementation here.
  • muka, for the agent implementation here.