wol-cli

A Wake-on-LAN magic packet sender with VLAN support.

Features

• UDP Broadcast: Standard Wake-on-LAN via UDP broadcast
• Directed Broadcast: Auto-compute broadcast address from CIDR notation
• 802.1Q VLAN Support: Send tagged Ethernet frames directly (Linux only, requires root)
• Device Aliases: Save device configurations for quick access

Installation

From PyPI

pip install wol-cli

From GitHub Releases (standalone binary)

Download the appropriate binary for your platform from the Releases page:

• wol-linux-amd64 - Linux x86_64
• wol-windows-amd64.exe - Windows x86_64
• wol-macos-amd64 - macOS x86_64

From source

pip install .

For development:

pip install -e ".[dev]"

Usage

Plain UDP Broadcast (same subnet)

wol AA:BB:CC:DD:EE:FF

Directed Broadcast

Auto-computes the broadcast address from a CIDR network:

wol AA:BB:CC:DD:EE:FF --network 192.168.10.0/24

802.1Q Tagged Frame (Linux only)

Send a VLAN-tagged raw Ethernet frame (requires root):

sudo wol AA:BB:CC:DD:EE:FF --vlan-id 10 --interface eth0

Using Aliases

Wake a device using its alias name instead of MAC address:

wol my-server

Options

Option	Description
--ip IP	Explicit broadcast/unicast IP (default: 255.255.255.255)
--port PORT	UDP port (default: 9)
--network CIDR	Subnet for directed broadcast (e.g., 192.168.10.0/24)
--vlan-id ID	802.1Q VLAN ID (1-4094)
--interface IFACE	Network interface for 802.1Q mode
--version	Show version

Alias Management

Aliases let you save device configurations for quick access. The configuration is stored in an OS-specific location:

OS	Config Path
Linux	~/.config/wol-cli/config.toml (or $XDG_CONFIG_HOME/wol-cli/config.toml)
macOS	~/Library/Application Support/wol-cli/config.toml
Windows	%APPDATA%\wol-cli\config.toml

Add an Alias

# Simple alias with just MAC address
wol alias add my-server AA:BB:CC:DD:EE:FF

# Alias with network settings
wol alias add my-server AA:BB:CC:DD:EE:FF --network 192.168.10.0/24

# Alias with VLAN settings
wol alias add my-server AA:BB:CC:DD:EE:FF --vlan-id 100 --interface eth0

# Alias with all options
wol alias add my-server AA:BB:CC:DD:EE:FF --ip 192.168.1.255 --port 7

List Aliases

wol alias list

Show Alias Details

wol alias show my-server

Remove an Alias

wol alias remove my-server

Show Config File Path

wol alias path

Library Usage

from wol_cli import send_udp, send_dot1q, build_magic_packet

# Send via UDP broadcast
send_udp("AA:BB:CC:DD:EE:FF")

# Send via directed broadcast
send_udp("AA:BB:CC:DD:EE:FF", ip="192.168.10.255")

# Build a magic packet manually
packet = build_magic_packet("AA:BB:CC:DD:EE:FF")

Alias Management (Programmatic)

from wol_cli import add_alias, get_alias, list_aliases, remove_alias, get_config_path

# Add an alias
add_alias("my-server", "AA:BB:CC:DD:EE:FF", network="192.168.10.0/24")

# Get alias configuration
config = get_alias("my-server")
# {'mac': 'AA:BB:CC:DD:EE:FF', 'network': '192.168.10.0/24'}

# List all aliases
aliases = list_aliases()

# Remove an alias
remove_alias("my-server")

# Get config file path
path = get_config_path()

Development

Install development dependencies:

pip install -e ".[dev]"

Run tests:

pytest -v

Run linter:

ruff check src/ tests/

Run type checker:

mypy src/

Releasing

Releases are automated via GitHub Actions.

How to Release

1. Update version in both files (must match):

   • pyproject.toml: version = "X.Y.Z"
   • src/wol_cli/__init__.py: __version__ = "X.Y.Z"

2. Create a PR and merge to main/master

3. The workflow automatically:

   • Validates versions match
   • Creates tag vX.Y.Z (if it doesn't exist)
   • Builds binaries for Linux, Windows, and macOS
   • Creates GitHub release with all artifacts
   • Publishes to PyPI

Note: If the tag already exists, no release is created (idempotent).

License

MIT