wifi-wand

Installation

Requirements: Ruby >= 3.2.0

To install this software, run:

gem install wifi-wand

or, you may need to precede that command with sudo to install it system-wide:

sudo gem install wifi-wand

Note for macOS users: macOS ships with Ruby 2.6. If you get an installation error about Ruby version or the traces gem, install a modern Ruby. The simplest way is with Homebrew:

brew install ruby

# Add to ~/.zshrc or ~/.bash_profile:
# Apple Silicon Macs:
export PATH="/opt/homebrew/opt/ruby/bin:$PATH"

# Intel Macs:
export PATH="/usr/local/opt/ruby/bin:$PATH"

<details> <summary><strong>Unsupported workaround for Ruby < 3.2</strong></summary>

If you must use an older Ruby version (not supported), you can try modifying wifi-wand.gemspec before building:

spec.required_ruby_version = ">= 2.7.0"    # change from ">= 3.2.0"
spec.add_dependency('async', '~> 1.30')    # change from '~> 2.0'

Then build and install:

gem build wifi-wand.gemspec
gem install wifi-wand-*.gem

Note: This configuration is not tested or supported. Use at your own risk.

</details>

Optional dependency for QR codes:

To use the wifi-wand qr command for generating Wi‑Fi QR codes, install qrencode.
- macOS: brew install qrencode
- Ubuntu: sudo apt install qrencode

⚠️ Important for macOS Users (10.15+)

After installation, run the one-time setup script:

wifi-wand-macos-setup

This grants location permission needed for WiFi network access. Without it, network names may appear as <hidden> or <redacted>. See the macOS Setup Guide for details.

Description

The wifi-wand gem enables the query and management of WiFi configuration, environment, and behavior, on Mac and Ubuntu systems. Internally, it uses OS-specific command line utilities to interact with the underlying operating system -- for example, networksetup, system_profiler, and ipconfig on macOS, and nmcli, iw, and ip on Ubuntu Linux. However, the code encapsulates the OS-specific logic in model subclasses with identical method names and argument lists, so that they present a unified interface for use in:

command line invocation (e.g. wifi-wand co my-network my-password to connect to a network)
interactive shell (REPL) sessions where the WiFi-wand methods are effectively DSL commands (wifi-wand shell to run in interactive mode)
other Ruby applications as a gem (library) (require wifi-wand)

⚠️ Breaking Change: Interactive Shell

The interactive shell is now a dedicated subcommand: run it with wifi-wand shell. The legacy -s/--shell option has been removed—update any scripts or aliases that still rely on the flag before upgrading.

Quick Start

# Display networking status (e.g.: WiFi: ON | Network: "my_network" | TCP: YES | DNS: YES | Internet: YES)
wifi-wand s

# Display WiFi on/off status
wifi-wand w

# See available WiFi networks
wifi-wand a

# Connect to a WiFi network with password
wifi-wand co MyNetwork password

# Connect to a WiFi network without password (if no password required or network is saved/preferred
wifi-wand co MyNetwork

# Force an open-network attempt even if a saved password exists
wifi-wand co MyNetwork ''

# Display detailed networking information
wifi-wand i

# Start interactive shell
wifi-wand shell

# Display underlying OS calls and their output
wifi-wand -v ...

Documentation

For detailed information about specific features:

Event Logging (log command) - Continuously monitor WiFi state changes, log events over time, and detect network issues
Status Command - Understand WiFi and connectivity status display
Info Command - Get detailed network configuration and status information
Connectivity Checking (ci command) - Check internet availability in scripts and automation
Testing Guide - Running tests, coverage reports, and test categories
DNS Configuration Guide - Managing nameservers and DNS settings
Environment Variables Reference - Configuration via environment variables (including the WIFIWAND_OPTS default-options helper)

Usage

Available commands can be seen by using the -h (or --help) option:

Command Line Switches     [wifi-wand version 3.0.0-alpha.1 at https://github.com/keithrbennett/wifiwand]
---------------------
-h, --help                - show this help message
-o, --output_format {i,j,k,p,y}
                          - when not in shell mode, outputs data in the following formats: inspect, JSON, pretty JSON, puts, YAML
-p, --wifi-interface interface_name
                          - specify WiFi interface name (overrides auto-detection)
-V, --version             - show version
-v, --[no-]verbose        - verbose mode (prints OS commands and their outputs)
                            To disable: use --no-verbose or --no-v (short form negation like -v- is not supported)

Subcommands
-----------
shell                     - start interactive shell (interactive pry REPL session)

Commands
--------
a[vail_nets]              - array of names of the available networks
ci                        - state of Internet connectivity, defined as both DNS and TCP working
co[nnect] network-name    - connects to the specified network-name, turning WiFi on if necessary
cy[cle]                   - toggles WiFi on/off state twice, regardless of starting state
d[isconnect]              - disconnects from current network, does not turn off WiFi
f[orget] name1 [..name_n] - removes network-name(s) from the preferred (saved) networks list
                            in interactive mode, can be a single array of names, e.g. returned by `pref_nets`
h[elp]                    - prints this help
i[nfo]                    - a hash of detailed networking information
lo[g]                     - start event logging (polls WiFi status, logs changes)
                            options: --interval N (default 5 seconds), --file [PATH] (default: wifiwand-events.log),
                                     --stdout (keep stdout when file destination is used)
                            Logs events: internet on/off
                            Ctrl+C to stop (see docs/LOGGING.md for details)
na[meservers]             - nameservers: 'show' or no arg to show, 'clear' to clear,
                            or IP addresses to set, e.g. '9.9.9.9  8.8.8.8'
ne[twork_name]            - name (SSID) of currently connected WiFi network
on                        - turns WiFi on
of[f]                     - turns WiFi off
pa[ssword] network-name   - password for preferred network name
pr[ef_nets]               - preferred (saved) networks
q[uit]                    - exits this program (interactive shell mode only) (same as 'x')
qr [filespec|'-'] [password]
                         - generate a Wi‑Fi QR code; default PNG file <SSID>-qr-code.png; '-' prints ANSI QR to stdout; '.svg'/' .eps' use those formats; optional password avoids macOS auth prompt
ro[pen]                   - open web resources: 'cap' (Portal Logins), 'ipl' (IP Location), 'ipw' (What is My IP), 'libre' (LibreSpeed), 'spe' (Speed Test), 'this' (wifi-wand home page)
s[tatus]                  - status line (WiFi, Network, TCP, DNS, Internet) with real-time connectivity checks
                            (see docs/STATUS_COMMAND.md for details on connectivity detection)
t[ill]                    - wait until Internet connection reaches desired state:
                            'on'/:on (connected), 'off'/:off (disconnected), 'conn'/:conn (connected), 'disc'/:disc (disconnected)
                            Optional: wait interval between checks in seconds (default: 0.5)
w[ifi_on]                 - is the WiFi on?
x[it]                     - exits this program (interactive shell mode only) (same as 'q')

When in interactive shell mode:
  * remember to quote string literals.
  * for pry commands, use prefix `%`, e.g. `%ls`.
  * To display the QR code in the shell, pass the string returned by `qr :-` to `puts`. Ex: `puts(qr :-)`

Pretty Output

The awesome_print gem is used for formatting output nicely in both non-interactive and interactive (shell) modes.

JSON, YAML, and Other Output Formats

You can specify that output in noninteractive mode be in a certain format. Currently, JSON, "Pretty" JSON, YAML, inspect, and puts formats are supported. See the help for which command line switches to use. In interactive mode, you can call the usual Ruby methods (to_json, to_yaml, etc.) instead.

Seeing the Underlying OS Commands and Output

If you would like to see the OS commands and their output, you can do so by specifying "-v" (for verbose) on the command line. To disable verbose mode, use --no-verbose or --no-v (Ruby's OptionParser does not support short-form negations like -v-).

Interactive Shell Mode vs Command Line Mode

Command Line Mode (default): Execute single commands and exit

wifi-wand info          # Run once, show output, exit
wifi-wand connect MyNet # Connect and exit

Interactive Shell Mode (shell subcommand): Start a persistent Ruby session

wifi-wand shell         # Enter interactive mode
[1] pry(#<WifiWandView>)> info
[2] pry(#<WifiWandView>)> connect "MyNet"
[3] pry(#<WifiWandView>)> cycle; connect "MyNet"

The shell is useful when you want to:

Issue multiple commands without restarting the program
Combine commands and manipulate their output with Ruby code
Use the data in formats not provided by the CLI
Shell out to other programs (prefix with .)
Work with the results interactively

If you gem install (or sudo gem install if necessary) the `pry-cooll

Wifiwand

Install / Use

README