wpa_cli

Scan for available networks

$ sudo wpa_cli scan

$ sudo wpa_cli scan_results

$ sudo wpa_cli [[add_n|add_network]] [number]

$ sudo wpa_cli [[set_n|set_network]] [number] ssid "[SSID]"

$ sudo wpa_cli [[en|enable_network]] [number]

$ sudo wpa_cli [[sa|save_config]]

wpa_cli [options] [command] [arguments]

Common usage:
wpa_cli [-i interface]
Non-interactive mode:
wpa_cli [-i interface] command [arguments]

-i interface
    Specify the network interface to control (e.g., wlan0, p2p-dev-wlan0). If not specified, wpa_cli attempts to guess.

-p path
    Specify the control interface path for wpa_supplicant (e.g., /var/run/wpa_supplicant).

-a action_file
    Run a specified script file when an event occurs, typically used in monitoring mode.

-B
    Run wpa_cli in the background. Useful for scripts that need to detach.

-P
    Enable program mode, primarily used by external programs or scripts to manage wpa_supplicant through a simpler event-based interface.

-v
    Show the version information of wpa_cli.

-h
    Display a short help message showing command-line options.

-s socket
    Specify the control socket path for interactive mode. Overrides the default or -p option for a specific socket file.

-g global_ctrl
    Connect to the global control interface of wpa_supplicant.

-t
    Attach to wpa_supplicant events (monitor mode). wpa_cli will display events as they happen.

-m
    Monitor mode, similar to -t, but may have subtle differences in how events are displayed or processed depending on the wpa_supplicant version.

wpa_cli is the command-line client for wpa_supplicant, the Wi-Fi Protected Access client. It provides an interface to control and monitor the wpa_supplicant daemon, which handles wireless authentication and encryption for Linux systems. Users can use wpa_cli to scan for available Wi-Fi networks, add and manage network configurations (SSIDs, passwords, security protocols), connect to or disconnect from networks, and view the current connection status. It supports both interactive mode, where users enter commands one by one, and non-interactive mode, where a single command is executed directly, making it suitable for scripting network configurations.

wpa_cli communicates with wpa_supplicant through a UNIX domain socket, allowing it to manage multiple interfaces if wpa_supplicant is configured to do so. It's an essential tool for headless systems, embedded devices, or for users who prefer command-line network management and direct interaction with the Wi-Fi stack.

Requires wpa_supplicant to be running and properly configured (e.g., with a control interface enabled) to function. If wpa_supplicant is not running or not accessible, wpa_cli will not be able to connect.

Permissions: Often requires root privileges (or to be part of the `netdev` or `wheel` group) to connect to wpa_supplicant's control interface and make configuration changes. Without sufficient permissions, connection attempts will fail.

Persistent configuration: Changes made via wpa_cli are often temporary and not persistent across system reboots unless explicitly saved to the wpa_supplicant configuration file (e.g., `/etc/wpa_supplicant/wpa_supplicant.conf`) using the save_config command within wpa_cli.

When run without a command (interactive mode), wpa_cli provides a prompt where users can type commands. Some frequently used commands include:

• status: Show current wpa_supplicant status and connection details.
• scan: Request a new scan for available Wi-Fi networks.
• scan_results: Display results from the last network scan.
• add_network: Add a new network configuration block.
• set_network <ID> ssid "SSID": Set the SSID for a network by its ID.
• set_network <ID> psk "password": Set the Pre-Shared Key (password) for a network.
• enable_network <ID>: Enable a specific configured network.
• select_network <ID>: Select and attempt to connect to a specific network.
• remove_network <ID>: Remove a network configuration by its ID.
• list_networks: List all currently configured networks with their IDs and states.
• save_config: Save the current wpa_supplicant configuration to its default file.
• disconnect: Disconnect from the currently associated network.
• reassociate: Reassociate with the current network (e.g., if connection drops).
• quit: Exit the wpa_cli interactive prompt.

On many Linux distributions, wpa_supplicant (and consequently wpa_cli) is often integrated with higher-level network management services like NetworkManager or systemd-networkd. While wpa_cli offers direct control, tools like nmcli (for NetworkManager) or networkctl (for systemd-networkd) are typically preferred for daily user interaction on desktop systems as they provide a more abstracted and user-friendly interface. However, wpa_cli remains invaluable for debugging wpa_supplicant issues, for scripting complex Wi-Fi setups, or for use in minimal environments where full network managers are not installed.

wpa_cli is an integral part of the wpa_supplicant project, which was primarily developed by Jouni Malinen starting around 2002-2003. It emerged as a robust solution for handling WPA, and later WPA2/WPA3, security protocols on Linux, addressing the limitations of older tools like iwconfig for modern wireless security. wpa_cli was designed as the primary user-facing command-line tool to interact with the wpa_supplicant daemon, providing a flexible way to manage complex wireless configurations. Its importance grew with the increasing adoption of Wi-Fi and its need for secure authentication, particularly for embedded systems, servers, and scripts where a graphical interface is not practical. Its development has consistently mirrored the evolution of Wi-Fi standards, integrating support for new features like P2P (Wi-Fi Direct) and advanced EAP methods.

wpa_supplicant(8), iwconfig(8), ip(8), nmcli(1), rfkill(8)