nmcli: Managing Networks from the Command Line

nmcli: Managing Networks from the Command Line
Reading time: About 10 min Difficulty: Intermediate

What You'll Learn

  • How to check network status with nmcli
  • How to connect to Wi-Fi and set a static IP entirely from the command line
  • The difference between a connection (profile) and a device (hardware), so your settings never silently disappear

Quick Summary

  • Inspect state → nmcli device status / nmcli connection show
  • Change settings → nmcli connection modify <name> <key> <value>
  • Apply changes → nmcli connection up <name>
  • Changes are persisted to a profile (they survive reboots)

Prerequisites (target environment)

  • A Linux system running NetworkManager (Ubuntu Desktop, RHEL, CentOS, Fedora, AlmaLinux, etc.)
  • nmcli ships with NetworkManager. Confirm it is running with systemctl status NetworkManager
  • Not applicable to servers managed solely by systemd-networkd or netplan

What is nmcli?

Conclusion: nmcli is the official command-line client for NetworkManager. It creates, edits, and persists connection settings without a GUI.

nmcli (NetworkManager Command Line Interface) is the official command for driving NetworkManager, the default network management daemon on most distributions. Almost everything you can do in the GUI network panel can be done with nmcli.

nmcli organizes its work around "objects." These five are the ones you'll use most:

Object Short Role
connection c Connection profile (the unit settings are saved in)
device d Physical / virtual network device
general g Overall NetworkManager state
radio r Wi-Fi / WWAN radio on/off
networking n Toggle all networking on/off

Object names can be abbreviated as long as the prefix is unique. nmcli connection show can be written nmcli c s. This article spells them out in full for clarity.

How do connection and device differ?

Conclusion: A device is real network hardware; a connection is a settings profile applied to it. Persistence lives on the connection side.

This is the single most important concept in nmcli.

  • device: An actual interface such as eth0, enp3s0, or wlan0. It reflects the current state (connected or not, current IP).
  • connection (profile): A saved settings file that says "configure this device like so." It lives under /etc/NetworkManager/system-connections/ and survives reboots.

You can keep several profiles (home, office) for a single device and switch between them with up.

Assigning an IP directly with ip addr add is lost on reboot. To persist it, you must edit the connection profile. This is the classic cause of "I configured it but the setting disappeared."

How do I check network status?

Conclusion: Use nmcli general status for the whole system, nmcli device status for devices, and nmcli connection show for profiles.

Start by understanding the current state. Running nmcli with no arguments prints full details for every device.

# Overall NetworkManager state
nmcli general status

# Device list (state and active profile)
nmcli device status

# Connection profile list
nmcli connection show
DEVICE  TYPE      STATE      CONNECTION
enp3s0  ethernet  connected  Wired connection 1
wlan0   wifi      connected  MyHome-WiFi
lo      loopback  unmanaged  --

To inspect a specific connection or device, add its name.

# Show all settings of a profile
nmcli connection show "Wired connection 1"

# Device details (IP, DNS, routes, etc.)
nmcli device show enp3s0

Use -f to limit the displayed fields. nmcli -f DEVICE,STATE device status makes the output easier to parse in scripts.

How do I connect to Wi-Fi?

Conclusion: List SSIDs with nmcli device wifi list, then connect with nmcli device wifi connect <SSID> password <password>.

Wi-Fi is a two-step scan-and-connect.

# Scan and list nearby Wi-Fi networks
nmcli device wifi list

# Connect with an SSID and password
nmcli device wifi connect "MyHome-WiFi" password "your-password"

On success, a connection profile of the same name is created automatically and reconnects on subsequent boots.

# Toggle the radio itself (like airplane mode)
nmcli radio wifi off
nmcli radio wifi on

To avoid leaving the password in your shell history, omit password and you'll be prompted interactively. Be mindful of history on shared servers.

How do I set a static IP?

Conclusion: Switch to ipv4.method manual, set ipv4.addresses / ipv4.gateway / ipv4.dns, then apply with connection up.

This is the operation you'll use most in server work. Here is the flow for switching from DHCP to a static IP.

# Check the profile name (assume "Wired connection 1" below)
nmcli connection show

# Set static IP, gateway, and DNS in one command
nmcli connection modify "Wired connection 1" \
  ipv4.method manual \
  ipv4.addresses 192.168.1.100/24 \
  ipv4.gateway 192.168.1.1 \
  ipv4.dns "8.8.8.8 1.1.1.1"

# Apply the changes (reactivate the profile)
nmcli connection up "Wired connection 1"
  • Always include the prefix length in ipv4.addresses, e.g. /24
  • For multiple DNS servers, quote a space-separated list: "8.8.8.8 1.1.1.1"
  • modify does not apply anything by itself. Only up applies the changes.

To go back to DHCP (automatic), set method to auto.

nmcli connection modify "Wired connection 1" ipv4.method auto
nmcli connection up "Wired connection 1"

To build a brand-new profile from scratch, use connection add.

nmcli connection add type ethernet con-name office-static ifname enp3s0 \
  ipv4.method manual ipv4.addresses 10.0.0.50/24 ipv4.gateway 10.0.0.1

How do I activate and deactivate connections?

Conclusion: nmcli connection up <name> activates, down deactivates, and connection delete removes the profile entirely.

# Activate (connect) a profile
nmcli connection up office-static

# Deactivate (disconnect, settings retained)
nmcli connection down office-static

# Delete a profile completely
nmcli connection delete office-static

down only drops the connection while keeping the profile, whereas delete removes the settings file itself. Don't confuse the two.

# Disconnect a whole device
nmcli device disconnect enp3s0

# Toggle all networking off/on
nmcli networking off
nmcli networking on

Common problems and fixes

Conclusion: Split issues into "device is unmanaged," "changes not applied," and "cannot connect" to reach the cause faster.

Device shows as unmanaged

If nmcli device status reports unmanaged, that device is outside NetworkManager's control. Another system such as /etc/netplan/ or /etc/network/interfaces is likely managing it.

# Let NetworkManager manage the device
nmcli device set enp3s0 managed yes

Modified but nothing changed

nmcli connection modify only rewrites the profile. Applying it to the live device requires up.

nmcli connection up "Wired connection 1"

I don't know the setting key

There are many configurable properties. List the current values to find the key you need.

# Show ipv4-related properties and current values
nmcli connection show "Wired connection 1" | grep ipv4

Before a risky change, record the current values with nmcli connection show <name> so you can roll back. On servers, secure console access before changing the IP in case you disconnect yourself remotely.

Summary / Next Reading

nmcli is the standard tool for managing networking on NetworkManager systems persistently and without a GUI. Once you grasp the split between device (hardware) and connection (profile), you can handle status checks, Wi-Fi, and static IPs with one consistent approach.