linktui
A fast, minimal terminal UI for managing Wi-Fi, Bluetooth, and WireGuard VPN on Linux β built with Bubble Tea.
Screenshots
πΈ Place your screenshots or GIF here
Recommended: a single animated GIF (800Γ400px) showing tab switching
Tools: ttyrec + gif-tty, asciinema, or vhs (https://github.com/charmbracelet/vhs)
Features
- Wi-Fi β scan nearby access points, connect with password prompt, manage saved profiles (autoconnect toggle, forget)
- Bluetooth β discover devices, pair with passkey confirmation, manage known devices, toggle power/discoverable/pairable
- WireGuard VPN β list tunnel profiles, activate/deactivate links, create new profiles via form, import
.conf files via file picker, display public IP info
- Tab navigation with
Tab / Shift+Tab
- Lazy-loads each tab on first visit for fast startup
- Fully themeable via
config.toml
- Respects configured window dimensions β warns if terminal is too small
Dependencies
Runtime
| Dependency |
Purpose |
| NetworkManager |
Wi-Fi and WireGuard VPN backend |
BlueZ (bluetoothd) |
Bluetooth backend via D-Bus |
| D-Bus |
IPC for BlueZ communication |
Ensure NetworkManager and BlueZ daemons are running:
sudo systemctl enable --now NetworkManager
sudo systemctl enable --now bluetooth
Build (Go modules)
| Module |
Used for |
charm.land/bubbletea/v2 |
TUI framework |
charm.land/lipgloss/v2 |
Terminal styling |
charm.land/bubbles/v2 |
Table, text input, file picker components |
github.com/Wifx/gonetworkmanager/v3 |
NetworkManager Go bindings |
github.com/godbus/dbus/v5 |
D-Bus bindings for BlueZ |
github.com/BurntSushi/toml |
Config file parsing |
Installation
AUR (Arch Linux)
# Using yay
yay -S linktui
# Using paru
paru -S linktui
# Manually
git clone https://aur.archlinux.org/linktui.git
cd linktui
makepkg -si
GitHub Releases (pre-built binary)
Download the latest binary from the Releases page.
# Download and install (replace VERSION and ARCH as needed)
curl -Lo linktui https://github.com/yourusername/linktui/releases/latest/download/linktui-linux-amd64
chmod +x linktui
sudo mv linktui /usr/local/bin/
Build from source
Requires Go 1.22+.
git clone https://github.com/yourusername/linktui.git
cd linktui
go build -o linktui ./cmd/linktui
sudo mv linktui /usr/local/bin/
Usage
# Open on the Wi-Fi tab (default)
linktui
# Open directly on a specific tab
linktui --tab wifi
linktui --tab bluetooth
linktui --tab vpn
Keybindings
| Key |
Action |
Tab / Shift+Tab |
Switch tabs |
j / k |
Navigate list up/down |
q |
Quit |
Ctrl+C |
Force quit |
Wi-Fi tab
| Key |
Action |
s |
Toggle scan mode |
Enter |
Connect (scan mode) / Options (saved mode) |
p |
Toggle adapter power |
Bluetooth tab
| Key |
Action |
s |
Start/stop discovery scan |
Enter |
Device actions menu |
p |
Toggle power |
d |
Toggle discoverable |
b |
Toggle pairable |
VPN tab
| Key |
Action |
n |
Create new WireGuard profile |
i |
Import .conf file |
Enter |
Actions menu (activate/deactivate/delete) |
p |
Fetch public IP info |
Configuration
linktui looks for a config file at:
~/.config/linktui/config.toml
If the file is absent, built-in defaults are used. All values are optional β only override what you need.
Example config.toml
[window]
width = 80
height = 28
[colors]
foreground = "#CDD6F4"
background = "#1E1E2E"
accent = "#89B4FA"
highlight = "#CBA6F7"
highlight_background = "#313244"
muted = "#6C7086"
border = "#45475A"
popup_background = "#181825"
log_background = "#11111B"
cursor = "#F5E0DC"
Note: width and height set the UI canvas size, not the terminal window size. The terminal must be at least as large as the configured dimensions β linktui will display a warning if it isn't.
Minimum dimensions
| Setting |
Minimum |
width |
70 |
height |
25 |
Ricing
Hyprland
linktui can be launched as a floating overlay window anchored to the top-right corner of your screen β useful as a quick-access panel triggered from a keybind or Waybar click.
Add this window rule to your hyprland.conf:
-- ### LINKTUI TOP RIGHT WINDOW RULE ###
hl.window_rule({
name = "linktui-top-right",
match = { title = "^(linktui)$" },
float = true,
size = "630 520",
move = { "monitor_w - window_w - 10", 50 },
})
Note on font rendering: The size values above assume a standard monospace font at a typical size (e.g. JetBrains Mono / Nerd Font at 12β13pt). If your terminal font is larger or smaller, the window may clip content or leave excess space. Tune width/height in your config.toml and the size rule together until the fit is clean. A good starting point: each character cell is roughly 8Γ16px at 12pt β so a 80Γ28 terminal canvas needs approximately 640Γ450px.
Waybar
The recommended setup uses a small toggle script so clicking a Waybar module opens linktui in a floating terminal and a second click closes it.
1. Create the toggle script
Save this to ~/.config/waybar/scripts/toggle-linktui.sh and make it executable:
chmod +x ~/.config/waybar/scripts/toggle-linktui.sh
#!/bin/bash
# ~/.config/waybar/scripts/toggle-linktui.sh
if pgrep -f "kitty.*linktui" >/dev/null; then
pkill -f "kitty.*linktui"
else
kitty --title "linktui" -e linktui "$1"
fi
Replace kitty with your terminal emulator. The --title "linktui" flag is what the Hyprland window rule matches on β keep it consistent.
2. Wire up the Waybar modules
Add on-click to your existing network and bluetooth module entries. Only the relevant lines are shown β merge these into your full module config:
"network": {
// ... your existing format/icon config ...
"on-click": "~/.config/waybar/scripts/toggle-linktui.sh --tab=wifi"
},
"bluetooth": {
// ... your existing format/icon config ...
"on-click": "~/.config/waybar/scripts/toggle-linktui.sh --tab=bluetooth"
}
Clicking the network widget opens linktui on the Wi-Fi tab; clicking again closes it. The bluetooth widget does the same on the Bluetooth tab.
Permissions
linktui communicates with system daemons over D-Bus and does not require sudo. Your user must be in the appropriate groups or have polkit policies that allow NetworkManager and BlueZ interactions.
On most distributions, logging in via a desktop session handles this automatically. If you run into permission errors in a minimal/headless setup:
# Add your user to the 'network' group if required by your distro
sudo usermod -aG network $USER
License
MIT β see LICENSE for details.