Gazelle

A minimal NetworkManager TUI for Linux with complete 802.1X enterprise WiFi support.

Why Gazelle?

A minimal, keyboard-driven TUI for NetworkManager with full 802.1X enterprise WiFi support. Perfect for connecting to eduroam, corporate networks, and regular WiFi from the terminal.

Installation

From AUR (Recommended)

yay -S gazelle-tui
# or
paru -S gazelle-tui

From GURU (Gentoo)

Documentation on GURU

$ # If you don't have GURU enabled already, you need to add it to your system.
$ sudo eselect repository enable guru

$ sudo emerge --ask net-misc/gazelle-tui::guru

Then just run:

gazelle

⚠️ Note for Omarchy Linux Users

If you get "target not found" errors for python-textual, python-rich, or python-platformdirs, your mirrors may be behind on Python packages. Use this safe workaround:

# Add official Arch mirrors (temporary)
sudo sed -i '1iServer = https://geo.mirror.pkgbuild.com/$repo/os/$arch' /etc/pacman.d/mirrorlist
sudo pacman -Syy

# Now install gazelle
yay -S gazelle-tui

Why this is safe:

• Omarchy uses official Arch repositories, this just adds the source directly
• Your Omarchy-specific packages are unaffected
• Temporary fix until Omarchy mirrors sync (typically 1-7 days)
• You can optionally remove the added line later with sudo sed -i '/geo.mirror.pkgbuild.com/d' /etc/pacman.d/mirrorlist

On Nix

1. Using Home Manager (recommended)

Add the Gazelle flake to your user flake:

inputs.gazelle.url = "github:Zeus-Deus/gazelle-tui";

Then enable it in your homeConfigurations:

modules = [
  gazelle.homeModules.gazelle
];

Don't forget to add the package as well:

    home.packages =  [
      inputs.gazelle.packages.${pkgs.system}.default
    ];

You can use Home Manager to declaratively configure Gazelle:

programs.gazelle = {
  enable = true;
  settings = {
    theme = "nord"; # choose your theme
  };

Home Manager will automatically generate:

~/.config/gazelle/config.json

with your chosen settings.

Apply the configuration:

home-manager switch

or rebuild your flake

nixos-rebuild switch --flake .#myFlake

---

2. Running the App Manually

Build and run with Nix:

nix build github:Zeus-Deus/gazelle-tui
./result/bin/gazelle

Or run directly with nix run:

nix run github:Zeus-Deus/gazelle-tui

---

Development Setup

For contributing or testing the latest version:

git clone https://github.com/Zeus-Deus/gazelle-tui.git
cd gazelle-tui
pip install -r requirements.txt
chmod +x gazelle
./gazelle

Omarchy Integration

To integrate Gazelle as your WiFi TUI in Omarchy (replacing Impala):

Step 1: Install Gazelle

# Temporarily add Arch mirrors (Omarchy mirror sync issue)
sudo sed -i '1iServer = https://geo.mirror.pkgbuild.com/$repo/os/$arch' /etc/pacman.d/mirrorlist
sudo pacman -Syy

# Install from AUR
yay -S gazelle-tui

Step 2: Choose Your Configuration Method

Important: Omarchy changed how terminals are launched in November 2025 (version ~3.1.5+), and again in February 2026 (version 3.2.0+) with the switch to Ghostty. Choose the configuration that matches your Omarchy version:

• Omarchy versions before November 2025 → Use Old Style configuration
• Omarchy versions from November 2025 onwards → Use New Style configuration

Old Style (Pre-November 2025 Omarchy)

For older Omarchy versions that launch terminals directly (like Alacritty/Kitty):

Configure Hyprland Window Rules:

Create a window rules configuration file:

cat > ~/.config/hypr/windows.conf << 'EOF'
# Gazelle WiFi TUI - floating window
# Old Hyprland Syntax
windowrule = tag +floating-window, match:class Gazelle
EOF

Add the source line to your Hyprland config:

echo "source = ~/.config/hypr/windows.conf" >> ~/.config/hypr/hyprland.conf

Update Waybar Network Module:

Edit ~/.config/waybar/config.jsonc and change the network module's on-click:

"network": {
    ...
    "on-click": "$TERMINAL --class=Gazelle -e gazelle"
}

New Style (November 2025+ Omarchy)

For newer Omarchy versions that use xdg-terminal-exec as a universal terminal launcher (including the default Ghostty terminal):

Configure Hyprland Window Rules:

Create a window rules configuration file:

cat > ~/.config/hypr/windows.conf << 'EOF'
# Gazelle WiFi TUI - floating window
# New Hyprland Syntax using match:initial_class (xdg-terminal-exec and Ghostty friendly)
windowrule = float on, center on, size 800 600, match:initial_class org.omarchy.Gazelle
EOF

Add the source line to your Hyprland config (if not already present):

echo "source = ~/.config/hypr/windows.conf" >> ~/.config/hypr/hyprland.conf

Update Waybar Network Module:

Edit ~/.config/waybar/config.jsonc and change the network module's on-click:

"network": {
    ...
    "on-click": "xdg-terminal-exec --app-id=org.omarchy.Gazelle -e gazelle"
}

Why the change?

• Omarchy uses xdg-terminal-exec as a universal terminal launcher.
• xdg-terminal-exec passes --app-id down to the default terminal.
• CRITICAL for Ghostty (Omarchy 3.2.0+ default): Ghostty is a GTK application and strictly requires a valid D-Bus application ID format (it must contain at least one period, e.g., org.omarchy.Gazelle). Passing a simple string like Gazelle will be rejected by GTK, causing the window rule to fail!
• Hyprland's windowrule with match:initial_class is required for proper window matching.

Step 3: Apply Changes

# Reload Hyprland configuration
hyprctl reload

# Restart Waybar
killall waybar && waybar &

Now clicking the WiFi icon in Waybar will launch Gazelle as a centered, floating 800x600 window on top of all other windows - exactly like Impala worked.

What This Does

Old Style: The floating-window tag automatically applies these rules (defined in Omarchy's system config):

• float - Window floats instead of tiling
• center - Centered on screen
• size 800 600 - Fixed size matching other Omarchy TUIs

New Style: The windowrule rules explicitly define:

• float - Window floats instead of tiling
• center - Centered on screen
• size 800 600 - Fixed size matching other Omarchy TUIs

Reverting to nm-applet

If you want to go back to nm-applet, change the waybar network on-click to:

"on-click": "nm-applet --indicator"

Features

• ✅ WWAN/Cellular Support - Manage 4G/5G modem connections with live signal monitoring
• ✅ Complete 802.1X Support (PEAP/TTLS/TLS with all phase2 auth methods)
• ✅ VPN Connection Management - Connect/disconnect OpenVPN and WireGuard VPNs
• ✅ Theme Persistence - Your theme choice is saved and restored between sessions
• ✅ Automatic Omarchy theme integration
• ✅ Hidden SSID Networks - Connect to networks that don't broadcast
• ✅ WPA3-OWE Support - Enhanced Open (encrypted open networks)
• ✅ Connect to regular WiFi (WPA/WPA2/WPA3-PSK)
• ✅ Connect to enterprise WiFi (eduroam, corporate networks)
• ✅ Scan for networks
• ✅ Auto-connect to known networks in range
• ✅ Toggle WiFi on/off
• ✅ Clean 4-section layout (Device, Station, Known Networks, New Networks)

802.1X Enterprise WiFi

Gazelle supports all common enterprise authentication methods:

EAP Methods:

• PEAP (most common, used by eduroam)
• TTLS
• TLS (certificate-based)

Phase 2 Authentication:

• MSCHAPv2 (most common)
• MSCHAP
• PAP
• CHAP
• GTC
• MD5

When connecting to an 802.1X network, simply select your authentication method from the dropdowns.

Keybindings

• j/k or ↓/↑ - Move cursor
• Tab - Switch between Known/New Networks sections
• Space - Connect to selected network
• s - Scan for networks
• h - Connect to hidden network
• v - VPN connections
• w - WWAN/Cellular connections
• d - Disconnect
• Ctrl+R - Toggle WiFi on/off
• Ctrl+P - Command palette (themes, etc.)
• ? - Show help
• q - Quit

Themes

Automatic Theme Matching (Omarchy)

Gazelle automatically detects and matches your Omarchy theme colors!

How it works:

• Omarchy users: Gazelle reads ~/.config/omarchy/current/theme/alacritty.toml (or ghostty.conf) and uses your exact theme colors
• Theme changes: Just restart Gazelle after changing Omarchy themes
• No configuration needed!

Supported:

• All Omarchy themes (nord, mars, gruvbox, catppuccin, tokyo-night, etc.)
• Colors update automatically when you switch themes

Non-Omarchy Users

If Omarchy is not detected, Gazelle uses standard ANSI terminal colors that work with any color scheme.

Manual Theme Override

To use a specific theme regardless of Omarchy:

1. Press Ctrl+P (command palette)
2. Search for "theme"
3. Select your preferred theme

Note: Manual theme selection is saved and persists across restarts.

Theme Customization

Gazelle supports all built-in Textual themes with automatic persistence.

Changing Theme:

1. Press Ctrl+P to open the command palette
2. Type "theme" and select from available themes
3. Your selection is automatically saved to ~/.config/gazelle/config.json
4. Theme persists across app restarts

Available Themes:

• textual-dark (default)
• textual-light
• nord
• dracula
• monokai
• gruvbox
• catppuccin
• tokyo-night
• ...and many more!

Config File Location: ~/.config/gazelle/config.json

Custom Themes

Create your own color schemes by editing ~/.config/gazelle/theme.toml. The file is automatically generated with commented examples on first run.

Omarchy Users: As long as you leave the theme.toml file commented out (default), your automatic theme syncing will continue working. Defining colors in this file will override the Omarchy theme.

Your custom theme appears as "user-theme" in the theme picker (Ctrl+P).

Custom Styles

Customize borders, spacing, and other TUI elements by adding a [styles] section to ~/.config/gazelle/theme.toml:

[styles]
dialog_border = "round"
section_border = "round"

Omarchy Users: Border styles are automatically matched to your Hyprland rounding and border size settings. No configuration needed.

Available border styles: none, ascii, blank, dashed, double, heavy, round, solid, thick, wide

All style options:

Option	Default	Description
dialog_border	solid	Modal dialog border style
section_border	solid	Section container border style
dialog_width	60	Modal dialog width
dialog_padding	1 2	Modal dialog padding
section_margin	1 2	Section margin
section_padding	0 1	Section padding
info_section_height	5	Device/Station section height
cursor_opacity	30%	Selection highlight opacity
hover_opacity	20%	Hover highlight opacity

Connecting to eduroam

1. Select eduroam network (shows as "802.1x" in Security column)
2. Press Space
3. Choose EAP Method: PEAP (default)
4. Choose Phase 2: MSCHAPv2 (default)
5. Enter username (e.g., user@university.edu)
6. Enter password
7. Connect!

The connection is saved and will auto-reconnect when in range.

Connecting to Hidden Networks

Many corporate/enterprise networks hide their SSID for security.

1. Press h (Hidden)
2. Enter the network name (SSID)
3. Select security type (Open/WPA2/802.1X)
4. Enter credentials if needed
5. Connect!

WPA3-OWE (Enhanced Open)

Gazelle automatically detects and connects to OWE networks (shown as "owe" in Security column). These are encrypted open networks that provide better security than traditional open WiFi. NetworkManager handles the encryption automatically - just connect like any open network.

VPN Support (Phase 1)

Gazelle now supports managing VPN connections directly from the TUI!

Phase 1 Features (v1.5+):

• List all configured VPN connections
• Connect/disconnect with keyboard
• Visual status indicators (🟢 connected, ⚪ disconnected)\n- Press v to open VPN screen

Setting Up VPN Connections

Phase 1 requires pre-configured VPN connections. Here's how to set them up:

1. Import VPN Config

sudo nmcli connection import type openvpn file your-vpn.ovpn

2. Store Credentials (optional - prevents password prompts)

sudo nmcli connection modify <vpn-name> \
    vpn.user-name "YOUR_USERNAME" \
    vpn.secrets "password=YOUR_PASSWORD" \
    +vpn.data "password-flags=0"

For NordVPN users: Get service credentials from nordaccount.com/manual-configuration (not your regular login)

3. Use Gazelle

• Press v to open VPN screen
• Use Enter or Space to connect/disconnect
• Press j/k to navigate, r to refresh

WireGuard VPN Setup

1. Import WireGuard Configuration

The .conf file must have a valid interface name (e.g., wg0.conf):

sudo nmcli connection import type wireguard file /path/to/wg0.conf

2. Disable Auto-Connect (optional)

By default, WireGuard connections auto-connect at boot. To disable:

nmcli connection modify wg0 autoconnect no

3. Manual Connection Control

Connect:

nmcli connection up wg0

Disconnect:

nmcli connection down wg0

4. Use Gazelle

Once imported, your WireGuard connection appears in Gazelle's VPN screen:

• Press v to open VPN screen
• Select your WireGuard connection
• Use Enter or Space to connect/disconnect

Phase 2 Coming: Import .ovpn files directly from Gazelle, edit connections, and more advanced features. See [Issue #3](https://github.com/Zeus-Deu