You are on a fresh Fedora install
The desktop environment failed to start, or you are managing a headless workstation with a USB WiFi adapter. The network manager applet is missing. You need internet access to pull packages, but the only interface available is the terminal. You run ip a and see the wireless interface is up but has no IP address. The hardware is detected, but it is not talking to any access point.
What's actually happening
NetworkManager controls all network interfaces on Fedora. It runs as a background daemon and manages connection profiles, DHCP leases, and DNS resolution. When you configure WiFi from the terminal, you are sending instructions directly to that daemon through nmcli. The command-line interface does not guess your intentions. It expects explicit instructions about which device to target, which SSID to associate with, and how to handle authentication.
The WiFi hardware operates in managed mode by default. It scans for beacon frames, requests an association, completes a WPA2 or WPA3 handshake, and then asks NetworkManager for an IP address via DHCP. If the driver lacks firmware, the security protocol mismatches, or the profile contains a typo, the interface stays in a disconnected or failed state. NetworkManager logs every attempt. Reading those logs tells you exactly where the handshake broke.
Run journalctl -xeu NetworkManager before guessing. The explanatory text and end-of-jump flags show the actual failure point in real time.
Checking device state versus connection state
Run this to confirm the wireless interface is recognized and ready for configuration.
nmcli device status
# Lists every network interface and its current state
# Look for the wireless device. It should show "disconnected" or "unmanaged"
# If it shows "unmanaged", NetworkManager is ignoring it due to a config override
NetworkManager separates the physical hardware from the logical configuration. The device commands talk to the radio and the driver. The connection commands talk to the saved profiles. A device can be connected to one profile while another profile sits idle in the configuration directory. If the device shows unmanaged, check /etc/NetworkManager/NetworkManager.conf for a [device] section that excludes it. Fedora enables WiFi management by default. An unmanaged state usually means a leftover configuration from a previous Linux install or a manual edit that broke the daemon's device policy. Fix the config file and restart the service before proceeding.
Never edit files in /usr/lib/NetworkManager/. Those ship with the package and get overwritten on updates. Keep your overrides in /etc/NetworkManager/ and let the daemon merge them on startup.
Scanning and connecting to a network
Run this to see which access points the adapter can reach.
nmcli device wifi list
# Queries the wireless interface for beacon frames
# Returns SSID, mode, channel, rate, signal strength, and security type
# Add --rescan yes if the list looks stale or empty
The output shows the security column as WPA2, WPA3, or WPA2/WPA3. Match your password entry to the protocol. WPA3 networks require a stronger passphrase and will reject short or dictionary-based passwords during the 4-way handshake. If the list is empty, verify that the interface is not blocked by rfkill. Run rfkill list and unblock soft or hard blocks before scanning again.
Run this to create a profile and activate the connection immediately.
nmcli device wifi connect "YourNetworkName" password "YourPassword"
# Creates a new connection profile in /etc/NetworkManager/system-connections/
# Triggers the authentication handshake and requests a DHCP lease
# The command blocks until the interface gets an IP address or times out
NetworkManager saves the credentials in a plaintext file under /etc/NetworkManager/system-connections/. The file is owned by root and has 600 permissions. You do not need to edit it manually. The daemon reads it on boot and applies the settings automatically. If you change the password later, update the profile through nmcli rather than touching the file directly. Manual edits drift and break validation checks.
Run this when the access point does not broadcast its SSID.
nmcli device wifi connect "HiddenSSID" password "YourPassword" hidden yes
# Forces the interface to probe for a specific SSID instead of waiting for beacons
# Adds the hidden flag to the profile so future connections use the same method
# Probing takes longer than passive scanning. Expect a few extra seconds
Enterprise networks using WPA2-Enterprise or WPA3-Enterprise require a different authentication flow. The nmcli device wifi connect command only handles WPA-Personal (PSK). For 802.1X networks, you must create the connection profile first, then set the 802.1X properties, and finally activate it. The terminal interface handles this through nmcli connection add followed by nmcli connection modify. Keep the personal and enterprise workflows separate. Mixing them causes authentication loops.
Always run nmcli connection show --active after connecting. Verify the profile name matches what you expect before opening a browser.
Managing existing profiles
Run this to list every saved WiFi configuration on the system.
nmcli connection show
# Displays all stored profiles regardless of connection state
# Shows UUID, connection name, type, and device assignment
# Use the connection name or UUID for subsequent modify commands
Profiles persist across reboots. If you travel between locations, you might accumulate profiles for home, coffee shops, and office networks. NetworkManager automatically activates the highest-priority profile that matches the current SSID. You can change the priority by adjusting the connection.autoconnect-priority property. Higher numbers win.
Run this to update an existing profile without deleting it.
nmcli connection modify "OldNetworkName" wifi-sec.psk "NewPassword"
# Updates the PSK field in the stored profile
# Does not trigger a reconnect. The change applies on the next activation
# Preserves all other settings like IPv4 method and DNS configuration
If you need the change to take effect immediately, disconnect and reconnect using the profile name. Run nmcli connection down "OldNetworkName" followed by nmcli connection up "OldNetworkName". The daemon tears down the old session and negotiates a fresh handshake with the new credentials.
Delete orphaned profiles regularly. They clutter the configuration directory and can trigger unwanted autoconnect attempts in public spaces.
Verifying the connection
Run this to confirm the interface has an IP address and is routing traffic.
nmcli connection show --active
# Displays all active connections and their associated devices
# Look for the WiFi profile name and the IPv4 address column
# An empty IPv4 column means DHCP failed or the lease is pending
If the IP address is missing, check the DHCP client logs. Run journalctl -xeu NetworkManager and look for DHCP4 or DHCP6 entries. A timeout usually means the router is not responding, or the MAC address is blocked by a firewall policy. Verify your router's client list. If the lease appears but you cannot reach external hosts, check your DNS configuration. NetworkManager pulls DNS servers from the DHCP offer. Run resolvectl status to see which nameservers are active.
Ping an external DNS server to isolate routing issues from name resolution issues. Run ping -c 3 8.8.8.8. If the pings succeed but ping google.com fails, your DNS configuration is broken. If both fail, your default route is missing or the firewall is dropping outbound traffic.
Check the routing table with ip route. The default route should point to your router's IP address. If it points to 127.0.0.1 or is missing entirely, NetworkManager failed to install the route. Restart the connection profile and watch the journal output.
Common pitfalls and what the error looks like
You will see this error when the driver cannot associate with the access point.
Error: Connection activation failed: No suitable device found for connection 'YourNetworkName'.
The device is either blocked, disabled, or operating on a frequency band the hardware does not support. Many USB adapters only handle 2.4 GHz. If your router broadcasts a single SSID for both 2.4 GHz and 5 GHz, the adapter might fail to lock onto the 5 GHz channel. Force the connection to the 2.4 GHz band by checking the channel column in the scan output. Channels 1 through 11 are 2.4 GHz. Channels 36 and above are 5 GHz.
You will see this error when the password is wrong or the security protocol mismatches.
Error: Connection activation failed: The 802.1X supplicant could not connect to the supplicant agent.
This usually means the passphrase contains special characters that the shell interpreted, or the network uses WPA3 while the adapter only supports WPA2. Wrap the password in single quotes to prevent shell expansion. If the hardware is older, it might lack the cryptographic offload required for WPA3. Check the kernel logs for cfg80211 or mac80211 warnings. Downgrade the router to WPA2-Personal if the adapter cannot negotiate the newer protocol.
You will see this error when MAC randomization interferes with router policies.
Error: Connection activation failed: Device not ready.
Fedora enables MAC address randomization for WiFi by default to improve privacy. Some enterprise routers or strict home firewalls reject randomized MACs. Disable randomization for the specific profile by running nmcli connection modify "YourNetworkName" wifi.cloned-mac-address permanent. The interface will use the factory MAC address instead. Reconnect after applying the change.
You will see this warning when the connection drops repeatedly.
Warning: Connection activation failed: DHCP client lost lease.
The router is reclaiming the IP address, or another device on the network is claiming the same lease. Check for duplicate MAC addresses on your network. If you are on a corporate network, the DHCP lease time might be extremely short. Adjust the ipv4.dhcp-timeout property in the profile to match the network's expectations.
Run journalctl -t setroubleshoot if SELinux blocks a custom script from accessing the network interface. SELinux denials show up with a one-line summary. Read those before disabling the policy.
When to use this vs alternatives
Use nmcli when you need to script network configuration or manage a headless system without a display server. Use nmtui when you prefer a terminal-based menu interface that guides you through profile creation and activation. Use the desktop network applet when you are running a graphical session and want automatic connection switching. Stay with nmcli when you are writing automation that requires predictable exit codes and machine-readable output.
Trust the package manager for driver updates. Manual firmware drops drift, snapshots stay.