nmcli Command in Linux: NetworkManager CLI Reference

When a Linux system needs a network change from a terminal, nmcli is usually the cleanest way to make it. It controls NetworkManager, the service that handles wired, wireless, VPN, and other connection profiles on many Linux desktops and servers.

This guide explains how to inspect device status, list and edit connections, join Wi-Fi networks, assign a static IP address, and get script-friendly output with nmcli.

Before You Begin #

Before changing network settings, confirm that NetworkManager is installed and running:

systemctl status NetworkManager

On distributions that use a different network stack, install NetworkManager from the package manager and enable the service before continuing. Most Ubuntu, Fedora, and Arch desktops have it preinstalled.

If you are connected over SSH , be careful with commands that disconnect an interface, change an address, or bring a profile down. A wrong gateway, IP address, or device name can drop the remote session.

nmcli Syntax #

The general nmcli syntax is:

nmcli [OPTIONS] OBJECT { COMMAND | help }

OBJECT is the part of NetworkManager you want to inspect or change. The most common objects are:

• general - show overall NetworkManager status and hostname settings
• networking - enable, disable, or check networking
• radio - control Wi-Fi and WWAN radio switches
• device - show and manage network interfaces
• connection - show and manage saved connection profiles
• monitor - watch NetworkManager events in real time

You can abbreviate most objects, for example nmcli con show instead of nmcli connection show, but the full form is clearer in scripts and documentation.

Show General Status #

The general subcommand reports the overall NetworkManager state, the hostname, and whether networking is enabled:

nmcli general status

STATE      CONNECTIVITY  WIFI-HW  WIFI     WWAN-HW  WWAN
connected  full          enabled  enabled  enabled  enabled

Read or change the system hostname through the same subcommand:

nmcli general hostname
sudo nmcli general hostname server01

The second form writes the new hostname to /etc/hostname and updates the kernel value without a reboot. For more hostname options, see the guide on changing the hostname in Linux .

Manage Devices #

A device in NetworkManager is a physical or virtual interface, for example eth0, wlan0, or wg0. List every known device with:

nmcli device status

DEVICE  TYPE      STATE      CONNECTION
eth0    ethernet  connected  Wired connection 1
wlan0   wifi      connected  home-wifi
lo      loopback  unmanaged  --

Show detailed properties of a single device, including the MAC address, driver, and current IP configuration:

nmcli device show eth0

Bring an interface up or down without changing the underlying connection profile:

sudo nmcli device connect eth0
sudo nmcli device disconnect eth0

disconnect stops the connection but keeps the profile available for the next connect call. Do not disconnect the device that carries your current SSH session unless you have another access path.

Manage Connection Profiles #

NetworkManager stores each network as a connection profile under /etc/NetworkManager/system-connections/. List every profile:

nmcli connection show

NAME                UUID                                  TYPE      DEVICE
Wired connection 1  3f4e...                                ethernet  eth0
home-wifi           7a92...                                wifi      wlan0

Activate a saved profile by name:

sudo nmcli connection up "home-wifi"

Deactivate it without deleting the profile:

sudo nmcli connection down "home-wifi"

Delete a profile when it is no longer needed:

sudo nmcli connection delete "home-wifi"

Deleting a profile removes the saved NetworkManager configuration. If you only want to stop using it for the moment, bring it down instead.

Connect to a Wi-Fi Network #

Scan for available networks. The radio must be on for the scan to return results:

nmcli device wifi list

Join an open or WPA2 network in one call. NetworkManager creates a new profile and stores the password in the system keyring:

sudo nmcli device wifi connect "home-wifi" password "secret-passphrase"

Avoid putting real Wi-Fi passwords in shell history, shared scripts, or configuration repositories. For interactive use, run sudo nmcli --ask device wifi connect "home-wifi" so nmcli prompts for the password instead.

For hidden networks, add the hidden yes flag so NetworkManager probes the SSID directly:

sudo nmcli device wifi connect "office-hidden" password "secret-passphrase" hidden yes

Turn the radio on or off without removing saved profiles:

sudo nmcli radio wifi off
sudo nmcli radio wifi on

Configure a Static IP Address #

Static addressing is one of the most common scripted changes on a server. The example below sets a static IPv4 address, gateway, and DNS servers on the existing Wired connection 1 profile:

sudo nmcli connection modify "Wired connection 1" \
  ipv4.method manual \
  ipv4.addresses 192.168.1.50/24 \
  ipv4.gateway 192.168.1.1 \
  ipv4.dns "1.1.1.1 9.9.9.9"

Apply the change by reactivating the profile:

sudo nmcli connection up "Wired connection 1"

If you are changing a remote machine, confirm the address, prefix, gateway, and DNS values before running connection up. A wrong value can make the host unreachable. On Ubuntu systems that use Netplan instead, see the guide on configuring a static IP address on Ubuntu .

Switch back to DHCP at any point with:

sudo nmcli connection modify "Wired connection 1" \
  ipv4.method auto \
  ipv4.addresses "" \
  ipv4.gateway "" \
  ipv4.dns ""
sudo nmcli connection up "Wired connection 1"

The empty values clear the manual entries that would otherwise stay on the profile.

Add a New Wired Connection #

When the default profile is missing or has been deleted, create a fresh ethernet profile:

sudo nmcli connection add type ethernet ifname eth0 con-name "wired-static" \
  ipv4.method manual \
  ipv4.addresses 192.168.1.50/24 \
  ipv4.gateway 192.168.1.1 \
  ipv4.dns 1.1.1.1
sudo nmcli connection up "wired-static"

This pattern works well in provisioning scripts when you first check whether the profile exists, or when you intentionally replace a known profile. If you only need to change an existing profile, use connection modify instead of deleting and recreating it.

Set DNS Servers #

You can change DNS servers without changing the IP address method. For example, to set Cloudflare and Quad9 DNS on a wired profile:

sudo nmcli connection modify "Wired connection 1" ipv4.dns "1.1.1.1 9.9.9.9"
sudo nmcli connection up "Wired connection 1"

To append another DNS server instead of replacing the whole list, prefix the property with +:

sudo nmcli connection modify "Wired connection 1" +ipv4.dns 8.8.8.8

After changing DNS, verify name resolution with a lookup tool such as dig or nslookup .

Common Examples #

Show only the active connections in a parseable format. The -t flag enables terse output and -f selects fields:

nmcli -t -f NAME,DEVICE connection show --active

Watch interface events in real time, useful when a connection drops during a remote session:

nmcli monitor

Reload all profile files from disk after editing them by hand:

sudo nmcli connection reload

For low-level interface and route inspection outside NetworkManager, pair nmcli with the ip command .

Quick Reference #

For a printable quick reference, see the nmcli cheatsheet .

Troubleshooting #

Error: NetworkManager is not running
Start the service with sudo systemctl start NetworkManager and enable it at boot with sudo systemctl enable NetworkManager. On a fresh server install, the package may not be present yet.

Wi-Fi list is empty after nmcli device wifi list
The radio is most likely off. Run sudo nmcli radio wifi on, and check that no rfkill switch is blocking the device with rfkill list.

A new static IP does not take effect
NetworkManager applies the change only after the connection is reactivated. Run sudo nmcli connection up <name> after connection modify. If a stale DHCP lease is still in place, run sudo nmcli connection down <name> first.

Not authorized to control networking
The operation requires administrator privileges or a PolicyKit rule that allows the current user. Run the command with sudo, or ask the system administrator to grant the needed NetworkManager permissions.

A profile keeps reverting to DHCP after reboot
A second profile or a cloud-init configuration may be overwriting it. Check /etc/NetworkManager/system-connections/ and /etc/netplan/ for conflicting files.

Conclusion #

nmcli gives you a scriptable way to inspect NetworkManager state, activate profiles, join Wi-Fi networks, and make persistent IP and DNS changes. For deeper network troubleshooting, use it alongside ip, ss, dig, and the system logs so you can see both the saved profile and the live kernel state.

About the authors

Dejan Panovski

Dejan Panovski is the founder of Linuxize, an RHCSA-certified Linux system administrator and DevOps engineer based in Skopje, Macedonia. Author of 800+ Linux tutorials with 20+ years of experience turning complex Linux tasks into clear, reliable guides.

View author page