DEV Community

Cover image for Recovering Wi-Fi Access on a Headless Raspberry Pi with `nmcli`
Ikegbo Ogochukwu
Ikegbo Ogochukwu

Posted on

Recovering Wi-Fi Access on a Headless Raspberry Pi with `nmcli`

#ai #iot #terminal #cli

If you manage Raspberry Pis remotely, eventually you'll run into this problem:

The Raspberry Pi needs new Wi-Fi credentials, but there is no keyboard, monitor, or physical access to configure it.

This happened to me while working with a headless Raspberry Pi. The Pi was connected through SSH, and I needed to update its Wi-Fi credentials without accidentally locking myself out.

The solution was NetworkManager + nmcli.

What You'll Need

  • Raspberry Pi running Raspberry Pi OS with NetworkManager
  • SSH access to the Pi
  • Access to the Wi-Fi router/hotspot
  • The new Wi-Fi password
  • Another computer on the network for SSH

NetworkManager treats Wi-Fi configurations as connection profiles. These profiles can be inspected, modified, activated, and deactivated using nmcli.

1. Check the NetworkManager status

Start by checking the network devices:

nmcli device status
Enter fullscreen mode Exit fullscreen mode

Example:

DEVICE   TYPE      STATE      CONNECTION
wlan0    wifi      connected  dex
lo       loopback  connected   lo
Enter fullscreen mode Exit fullscreen mode

Here:

  • wlan0 is the Raspberry Pi's Wi-Fi interface.
  • dex is the active Wi-Fi connection profile.

2. List saved Wi-Fi profiles 

nmcli connection show
Enter fullscreen mode Exit fullscreen mode

Example:

NAME                 UUID                                  TYPE      DEVICE
dex                  140ad8be-fcc2-475c-95af-e0491b93760a  wifi      wlan0
lo                   588680fc-bd8f-4526-9eb1-af8640764a0e  loopback  lo
MTN_4G_320E79        b9b81206-1ec4-4000-8c96-2d69716c1acd  wifi      --
Wired connection 1   13d4485f-0739-3ae3-9c21-6a8fd811361a  ethernet  --
Enter fullscreen mode Exit fullscreen mode

The important part is identifying which profile is currently connected.

In my case:

dex → wlan0
Enter fullscreen mode Exit fullscreen mode

3. Check the current IP address

Before changing anything, record the Raspberry Pi's IP address:

hostname -I
Enter fullscreen mode Exit fullscreen mode

For example:

192.168.0.6
Enter fullscreen mode Exit fullscreen mode

This is important because after reconnecting, the router could assign the Pi a different IP address.

4. Scan for Wi-Fi networks

You can scan for available networks with:

nmcli device wifi list
Enter fullscreen mode Exit fullscreen mode

To force a fresh scan:

sudo nmcli device wifi rescan
Enter fullscreen mode Exit fullscreen mode

Then:

nmcli device wifi list
Enter fullscreen mode Exit fullscreen mode

NetworkManager's nmcli device wifi commands can list available access points and initiate Wi-Fi connections from the command line.

Changing the Wi-Fi Password Remotely

This is the important part.

Suppose the Wi-Fi network is:

SSID: dex
New password: NEW_PASSWORD
Enter fullscreen mode Exit fullscreen mode

Update the password stored in the Raspberry Pi's connection profile:

sudo nmcli connection modify "dex" wifi-sec.psk "NEW_PASSWORD"
Enter fullscreen mode Exit fullscreen mode

The wifi-sec.psk property represents the pre-shared key used for WPA Wi-Fi connections.

Important distinction

This command does not change the router's actual Wi-Fi password.

It changes the password saved in the Raspberry Pi's NetworkManager connection profile.

So the safe sequence is:

  1. Save the new password on the Pi.
  2. Change the actual password on the router/hotspot.
  3. Reconnect the Pi.

5. Enable automatic reconnection

I also recommend making sure the connection is configured to reconnect automatically:

sudo nmcli connection modify "dex" connection.autoconnect yes
Enter fullscreen mode Exit fullscreen mode

This is particularly useful for headless devices because you don't want to manually reconnect the Pi after every reboot.

6. Change the actual router Wi-Fi password

Now change the Wi-Fi password on your router/hotspot.

Use the same password that you stored in the Raspberry Pi:

Router password:
NEW_PASSWORD

Raspberry Pi saved password:
NEW_PASSWORD
Enter fullscreen mode Exit fullscreen mode

This is where the headless setup becomes useful.

You have already prepared the Pi for the new credentials before disconnecting it.

7. Reconnect the Raspberry Pi

After changing the router's password:

sudo nmcli connection down "dex"
Enter fullscreen mode Exit fullscreen mode

Then:

sudo nmcli connection up "dex"
Enter fullscreen mode Exit fullscreen mode

Your SSH session will probably disconnect.

That's expected.

The Pi is temporarily losing its Wi-Fi connection while it reconnects using the new credentials.

NetworkManager supports explicitly activating and deactivating connection profiles with nmcli connection up and nmcli connection down.

8. Wait and reconnect through SSH

Give the Pi around 10–20 seconds to reconnect.

Then try:

ssh pi@192.168.0.6
Enter fullscreen mode Exit fullscreen mode

If DHCP assigned the Pi a different address, you'll need to find the new IP from your router or another device on the network.

Connecting the Pi to a Completely Different Wi-Fi

If you're not changing the password of the existing network but want to connect the Pi to another Wi-Fi network, you can use:

sudo nmcli device wifi connect "WIFI_NAME" password "WIFI_PASSWORD"
Enter fullscreen mode Exit fullscreen mode

For example:

sudo nmcli device wifi connect "MyNewWiFi" password "MyNewPassword"
Enter fullscreen mode Exit fullscreen mode

NetworkManager can create and activate a connection profile when connecting to a new WPA-PSK network.

You can then check the connection:

nmcli device status
Enter fullscreen mode Exit fullscreen mode

And find the new IP:

hostname -I
Enter fullscreen mode Exit fullscreen mode

Useful nmcli Commands for Headless Raspberry Pi

Show network devices 

nmcli device status
Enter fullscreen mode Exit fullscreen mode

Show detailed Wi-Fi information 

nmcli device show wlan0
Enter fullscreen mode Exit fullscreen mode

Show saved connections 

nmcli connection show
Enter fullscreen mode Exit fullscreen mode

Show active connections 

nmcli connection show --active
Enter fullscreen mode Exit fullscreen mode

Scan Wi-Fi 

nmcli device wifi list
Enter fullscreen mode Exit fullscreen mode

Force Wi-Fi scan 

sudo nmcli device wifi rescan
Enter fullscreen mode Exit fullscreen mode

Connect to Wi-Fi 

sudo nmcli device wifi connect "SSID" password "PASSWORD"
Enter fullscreen mode Exit fullscreen mode

Activate a saved connection 

sudo nmcli connection up "CONNECTION_NAME"
Enter fullscreen mode Exit fullscreen mode

Deactivate a connection 

sudo nmcli connection down "CONNECTION_NAME"
Enter fullscreen mode Exit fullscreen mode

Change Wi-Fi password 

sudo nmcli connection modify "CONNECTION_NAME" wifi-sec.psk "NEW_PASSWORD"
Enter fullscreen mode Exit fullscreen mode

Enable automatic connection 

sudo nmcli connection modify "CONNECTION_NAME" connection.autoconnect yes
Enter fullscreen mode Exit fullscreen mode

Find IP address 

hostname -I
Enter fullscreen mode Exit fullscreen mode

A Safer Trick for Remote Changes

One particularly useful NetworkManager feature for remote administration is connection checkpoints.

NetworkManager can create a temporary checkpoint before making potentially disruptive network changes. If the change isn't confirmed, the configuration can automatically be restored after the timeout.

For example, NetworkManager supports:

sudo nmcli device checkpoint --timeout 60 -- wlan0
Enter fullscreen mode Exit fullscreen mode

This is useful when you're making network changes over SSH and are worried about locking yourself out.

Final Headless Wi-Fi Workflow

For future Raspberry Pi deployments, my basic workflow is:

# 1. Identify Wi-Fi interface
nmcli device status

# 2. Find active connection
nmcli connection show --active

# 3. Record IP
hostname -I

# 4. Update saved Wi-Fi credentials
sudo nmcli connection modify "dex" wifi-sec.psk "NEW_PASSWORD"

# 5. Enable automatic reconnection
sudo nmcli connection modify "dex" connection.autoconnect yes

# 6. Change the actual router password

# 7. Reconnect Pi
sudo nmcli connection up "dex"

# 8. Check connection
nmcli device status

# 9. Check IP
hostname -I
Enter fullscreen mode Exit fullscreen mode

The main lesson is simple:

When managing a headless Raspberry Pi, configure the new network credentials before breaking the existing connection.

That small precaution can save you from needing a physical keyboard and monitor just to recover Wi-Fi access.

Top comments (0)