The scenario
You SSH into a Fedora server to change a static IP, or you sit down at a new desktop and realize the GUI network settings are locked behind a session you do not have. The terminal is open. You need to change an IP address, switch a Wi-Fi network, or troubleshoot why a cable is plugged in but the interface shows no carrier. The nmcli command is your direct line to NetworkManager. It bypasses the desktop environment and talks straight to the daemon that controls your network stack.
What nmcli actually does
NetworkManager separates the physical hardware from the configuration profiles. A device is the actual interface like eth0 or wlan0. A connection is a named set of rules that tells the device how to behave. You can have three different connection profiles for one Wi-Fi card. One for your home network, one for a corporate guest network, and one for a hotspot. NetworkManager applies the profile that matches the current environment. nmcli is the command-line interface that reads, writes, and activates those profiles. Think of it like a radio. The hardware is the tuner. The connection profiles are the preset stations. nmcli is the remote control.
The daemon stores profiles in /etc/NetworkManager/system-connections/. Those files are user-modified and survive reboots. The daemon itself ships with default configuration in /usr/lib/NetworkManager/. Never edit files in /usr/lib/. Package updates will overwrite them. Edit /etc/ or use nmcli to generate the correct files automatically.
Run systemctl status NetworkManager before you touch any interface. The daemon must be active and running, or every command will fail silently or hang.
Managing connections with nmcli
Here is how to list every profile NetworkManager knows about, along with their current state.
nmcli connection show
# Lists all saved profiles, their UUIDs, and whether they are active
# The "NAME" column is what you will reference in every future command
# The "DEVICE" column shows which physical interface is currently using the profile
# An empty DEVICE column means the profile exists but is not attached to hardware
You will see output that separates saved profiles from active ones. If you only want to see what is currently passing traffic, filter by the active flag.
nmcli connection show --active
# Restricts output to profiles that are currently bound to a device
# Useful when you have dozens of saved Wi-Fi networks but only one is connected
# The UUID is generated automatically and should not be memorized
# Use the NAME column for human-readable management
Modifying an existing connection is where most administrators spend their time. You rarely delete profiles. You update them and reactivate them. Here is how to switch an interface from DHCP to a static IPv4 address.
nmcli connection modify office-eth0 ipv4.method manual
# Switches the IP configuration mode from automatic to manual
# NetworkManager will stop requesting a lease from a DHCP server
nmcli connection modify office-eth0 ipv4.addresses 192.168.10.50/24
# Sets the primary IP and subnet mask in CIDR notation
# You can append a second address separated by a space if needed
nmcli connection modify office-eth0 ipv4.gateway 192.168.10.1
# Defines the default route for outbound traffic
# Omit this line if the interface is on a segmented network without a gateway
nmcli connection modify office-eth0 ipv4.dns "8.8.8.8 1.1.1.1"
# Sets the DNS resolvers. Multiple values are space-separated and quoted
# NetworkManager writes these to /etc/resolv.conf or systemd-resolved
nmcli connection up office-eth0
# Applies the changes immediately without unplugging the cable
# NetworkManager tears down the old link and brings up the new configuration
Wi-Fi management follows a different workflow because the hardware must scan for beacons before it can associate. Here is how to discover available networks and join one.
nmcli device wifi list
# Scans for nearby access points and prints signal strength, security, and channel
# Requires root privileges or sudo because it triggers a hardware scan
# The SSID column may show hidden networks as <hidden>
nmcli device wifi connect "Corporate-Guest" password "TempPass123"
# Creates a new profile, sets the security type automatically, and activates it
# NetworkManager handles WPA2/WPA3 negotiation and stores the credentials
# The connection will auto-connect next time the SSID is in range
If you need to force a specific security protocol or disable auto-connect, modify the profile after creation. NetworkManager normalizes most wireless settings automatically, so manual tweaks are rarely required unless you are dealing with enterprise RADIUS or captive portals.
Always reactivate the connection after modifying it. Changes sit in the configuration file until you trigger an up command.
Verifying the configuration
Here is how to confirm that the interface actually received the IP you assigned and that routing is correct.
ip addr show dev eth0
# Displays the kernel-level interface state and assigned addresses
# Look for the "inet" line matching your static IP
# If the state shows DOWN, NetworkManager has not handed the interface to the kernel
nmcli device show eth0
# Shows the NetworkManager-level state, IP4, IP6, and DNS information
# The IP4.ADDRESS[1] field confirms what the daemon thinks is active
# DNS1 and DNS2 fields verify resolver propagation
When something fails to activate, the daemon logs the exact reason. Do not guess. Read the journal.
journalctl -xeu NetworkManager
# Pulls recent logs for the NetworkManager unit with explanatory context
# The -x flag adds man-page references for common errors
# The -e flag jumps to the end so you see the latest events first
# Look for lines marked "error" or "failed" near the timestamp of your command
Check the interface carrier state if the link stays down. A missing carrier means the physical layer is broken, not the configuration.
Verify the DNS resolution separately. NetworkManager may push addresses correctly but fail to update the resolver if systemd-resolved is misconfigured or if a third-party DNS manager is intercepting /etc/resolv.conf.
Common pitfalls and error messages
The nmcli connection up command will refuse to proceed and print Error: Connection activation failed: Device not managed by NetworkManager. This happens when NetworkManager explicitly ignores an interface. The daemon reads /etc/NetworkManager/NetworkManager.conf and checks the unmanaged-devices key. If your interface matches a MAC address, driver, or path pattern in that list, nmcli cannot touch it. Remove the interface from the unmanaged list and restart the daemon.
If you see Error: Connection activation failed: No suitable device found for this connection, the profile is bound to a specific hardware address that no longer exists. This is common when you clone a VM or replace a network card. Clear the hardware binding so the profile can attach to any available interface.
nmcli connection modify office-eth0 connection.interface-name ""
# Clears the hardcoded interface binding in the profile
# Allows the profile to activate on eth0, enp3s0, or whatever the kernel names it
nmcli connection up office-eth0
# Retries activation with the flexible binding
Another frequent issue is the Failed to bring up connection message followed by a timeout. This usually means the static IP you assigned is already in use on the network, or the gateway is unreachable. NetworkManager performs an ARP probe by default. If another machine replies with the same IP, the daemon aborts the activation to prevent a conflict. Change the IP or disable the duplicate address detection if you are in a controlled lab environment.
SELinux denials rarely block NetworkManager itself, but they can block third-party scripts that nmcli triggers. Check journalctl -t setroubleshoot if a custom dispatcher script fails. Read the one-line summary before disabling SELinux.
Always check the physical link before blaming the configuration. A loose cable or disabled Wi-Fi switch will produce identical timeout errors.
When to use nmcli versus alternatives
Use nmcli when you need scriptable, repeatable network configuration across headless servers or locked-down workstations. Use nmtui when you prefer a terminal-based menu but still want NetworkManager to handle the backend. Use the desktop network settings when you are on a graphical session and only need occasional manual changes. Stick to nmcli when you are writing automation or managing infrastructure at scale.
Where to go next
- How to Fix "WiFi Disabled by Hardware Switch" on Fedora
- How to Set Up OpenVPN Server on Fedora
- How to Set Up a Network Printer on Fedora
Run nmcli connection show --active first. Confirm what is actually attached before you start rewriting profiles.