netbird-tui

Interactive TUI for managing NetBird VPN connections — built with ratatui.

Features

• Auto-detects whether you're connected and jumps straight to the right screen
• Server List (when not connected): choose from configured management servers, auto-reconnect to last used, or add a new one on the spot
• Split connected view: Networks panel (left) + Peers list with detail block (right) — both visible at once, Tab switches focus
• Peer info: status, NetBird IP, latency, handshake, transfer — press Enter to copy hostname, Space to copy IP to clipboard
• Multi-server support via a simple TOML config — or works completely without a config file
• Auto-refresh every 3 seconds (toggleable)
• --status flag for non-interactive use in scripts / status bars

Build

cargo build --release
# binary: target/release/netbird-tui

Optionally symlink into PATH:

ln -sf "$(pwd)/target/release/netbird-tui" ~/.local/bin/netbird-tui

Config (optional)

~/.config/netbird-tui/servers.toml

[[servers]]
name = "Office"
url  = "https://mgmt.company.com:443"

[[servers]]
name = "Home Lab"
url  = "https://mgmt.homelab.local:443"

Field	Description
name	Display label shown in the TUI
url	Full management server URL including port
bin	(optional) Path to the netbird binary (default: netbird)

If the file doesn't exist the TUI still works — you can add servers interactively with [+ Add new server].

If exactly one server is configured it is pre-selected and the connection goes straight to that server when you press Enter — no extra choice needed.

Usage

# Launch interactive TUI (auto-detects state)
netbird-tui

# Print current status and network list, then exit
netbird-tui --status

# Help
netbird-tui --help

TUI — Server List screen

Shown automatically when NetBird is not connected.

╔═ netbird-tui ════════════════════════════════════════╗
║  ○  Not connected                                    ║
╚══════════════════════════════════════════════════════╝
╔═ Servers (2) ════════════════════════════════════════╗
║  › ○  Office     https://mgmt.company.com:443        ║
║    ○  Home Lab   https://mgmt.homelab.local:443      ║
║    ↻  Auto-connect  (reconnect to last used server)  ║
║    +  Add new server                                 ║
╚══════════════════════════════════════════════════════╝

Key	Action
↑ ↓	Navigate
Enter / Space	Connect to selected server · Auto-connect · Open add form
e	Edit selected server
x	Delete selected server (with confirmation)
t	Toggle auto-connect for selected server
n	Open Add new server form directly
/	Filter server list
q	Quit

TUI — Connected screen

Shown automatically when NetBird is connected. Both panels are always visible.

╔═ netbird-tui ══════════════════════════════════════════════════════════╗
║  ●  Connected  ·  Office                                               ║
║  IP 100.64.0.1  ·  Peers 3/5  ·  Signal ●  ·  ⟳ auto                 ║
╚════════════════════════════════════════════════════════════════════════╝
╔═ Networks  3/4 ══════╗ ╔═ Peers  3/5 ═══════════════════════════════╗
║  › ✔  office-net     ║ ║  › ●  peer-a.netbird.example    100.64.0.2 ║
║    ✔  dev-network    ║ ║    ●  peer-b.netbird.example    100.64.0.3 ║
║    ✔  staging        ║ ║    ○  peer-c.netbird.example    100.64.0.4 ║
║    ○  legacy         ║ ╚════════════════════════════════════════════╝
║                      ║ ╔═ peer-a.netbird.example ═══════════════════╗
║                      ║ ║  Status    Connected   ·   IP  100.64.0.2  ║
║                      ║ ║  Latency   21ms        ·   Direct  P2P     ║
╚══════════════════════╝ ╚════════════════════════════════════════════╝

Networks panel (Tab to focus):

Key	Action
↑ ↓	Navigate
Space	Toggle selected network on / off
a	Select all (if any off) · Deselect all (if all on)
n	Name current server (if connected to unnamed server)
/	Filter
Tab	Switch focus → Peers
s	Switch to server list
d	Disconnect (netbird down)
r	Toggle auto-refresh on / off
q	Quit

Peers panel (Tab to focus):

Key	Action
↑ ↓	Navigate
Enter	Copy hostname to clipboard
Space	Copy NetBird IP to clipboard
/	Filter by name or IP
Tab	Switch focus → Networks
s	Switch to server list
d	Disconnect
r	Toggle auto-refresh on / off
q	Quit

Build

cargo build --release
# binary: target/release/netbird-tui

Optionally symlink into PATH:

ln -sf "$(pwd)/target/release/netbird-tui" ~/.local/bin/netbird-tui

Config (optional)

~/.config/netbird-tui/servers.toml

[[servers]]
name = "Office"
url  = "https://mgmt.company.com:443"

[[servers]]
name = "Home Lab"
url  = "https://mgmt.homelab.local:443"

Field	Description
name	Display label shown in the TUI
url	Full management server URL including port
bin	(optional) Path to the netbird binary (default: netbird)

If the file doesn't exist the TUI still works — you can add servers interactively with [+ Add new server].

If exactly one server is configured it is pre-selected and the connection goes straight to that server when you press Enter — no extra choice needed.

Usage

# Launch interactive TUI (auto-detects state)
netbird-tui

# Print current status and network list, then exit
netbird-tui --status

# Help
netbird-tui --help

TUI — Server List screen

Shown automatically when NetBird is not connected.

╔═ netbird-tui ════════════════════════════════════════╗
║  ○  Not connected                                    ║
╚══════════════════════════════════════════════════════╝
╔═ Servers (2) ════════════════════════════════════════╗
║  › ○  Office     https://mgmt.company.com:443        ║
║    ○  Home Lab   https://mgmt.homelab.local:443      ║
║    ↻  Auto-connect  (reconnect to last used server)  ║
║    +  Add new server                                 ║
╚══════════════════════════════════════════════════════╝

Key	Action
↑ ↓	Navigate
Enter / Space	Connect to selected server · Auto-connect · Open add form
n	Open Add new server form directly
/	Filter server list
r	Reload status
q	Quit

TUI — Networks screen

Shown automatically when NetBird is connected.

╔═ netbird-tui ════════════════════════════════════════╗
║  ●  Connected  ·  Office                            ║
║  IP 100.64.0.1  ·  Peers 3/5  ·  Signal ●           ║
╚══════════════════════════════════════════════════════╝
╔═ Networks  [2 selected / 4] ═════════════════════════╗
║  › ✔  office-network                                ║
║    ✔  dev-network                                   ║
║    ○  staging                                       ║
║    ○  legacy                                        ║
╚══════════════════════════════════════════════════════╝

Key	Action
↑ ↓	Navigate
Space	Toggle selected network on / off
a	Select all networks (if any off) · Deselect all (if all on)
/	Filter network list
s	Switch back to server list (to change server)
d	Disconnect (netbird down)
r	Reload status and network list
q	Quit