Wifiwand


WifiWand

Installation

**Requirements:** Ruby >= 3.2.0

To install this software, run:

`gem install wifi-wand`

**Note for macOS users:** macOS may ship with an older Ruby version (or no Ruby at all on recent releases). If you get an installation error about the Ruby version, install a modern Ruby (e.g. `brew install ruby`).

Ruby < 3.2 is unsupported

Ruby versions older than 3.2 are unsupported because the source code uses modern Ruby syntax and APIs. If your system Ruby is too old, install a modern Ruby before installing `wifi-wand` (the gem name).

JRuby Compatibility

The test suite passes on JRuby, and to the best of our knowledge the project is fully JRuby-compatible. If you encounter any JRuby-specific issues, please open a GitHub issue, including as much detail as possible.

Optional Dependency for QR Codes

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

---

Security Notes

`WifiWand` is intended for individual users on machines they control. Some workflows can expose WiFi passwords to local surfaces such as shell history, process listings, verbose output, terminal scrollback, and generated QR code files. See **[Security Notes](docs/SECURITY_NOTES.md)** for the full list of potential exposure points and practical precautions.

---

🐧 Note for Ubuntu Users

Ubuntu support requires **NetworkManager** (standard on Ubuntu Desktop). `WifiWand` uses `nmcli`, `iw`, and `ip` to manage WiFi. These are typically pre-installed on Ubuntu systems.

---

⚠️ Important for macOS Users (14+)

**On macOS 14 or later, install the macOS helper application after gem installation:**

wifiwand-macos-setup

This installs the `wifiwand-helper` helper application and grants the Location Services permission needed for unredacted WiFi network names. Without the helper applic