nmcli

nmcli is the command-line client for NetworkManager, the network configuration daemon used by most desktop and many server Linux distributions. It lets administrators create, modify, activate and monitor network connections and devices from a terminal or script, with changes stored as persistent connection profiles rather than temporary kernel settings.

In Linux networking, nmcli occupies the space between low-level tools and full configuration systems. The ip command changes the kernel’s network state immediately but forgets it at reboot; nmcli instructs NetworkManager, which applies and remembers the configuration and reacts to events such as a cable being plugged in or a Wi-Fi network appearing.

How nmcli works with NetworkManager

nmcli does not configure interfaces directly. It talks to the NetworkManager daemon over D-Bus, and the daemon performs the actual work: bringing links up, running DHCP, writing DNS settings, managing Wi-Fi authentication and handling VPN plugins. Because of this design, nmcli, the graphical applet and the text interface nmtui all see the same state.

The central concept is the difference between a device and a connection. A device is a network interface such as enp1s0 or wlp2s0. A connection, also called a profile, is a named set of settings that can be applied to a device. One device can have several profiles, for example office and home, but only one is active at a time.

Profiles are stored as keyfiles in /etc/NetworkManager/system-connections/ on current distributions, or in legacy ifcfg files on older Red Hat family systems. Files containing secrets such as Wi-Fi keys must be readable only by root.

Key connection properties and syntax

Connection settings are organized as setting.property pairs, such as ipv4.method or 802-11-wireless.ssid. nmcli accepts unambiguous abbreviations, so nmcli c s equals nmcli connection show, although full words are clearer in scripts and documentation.

A plus or minus prefix adds or removes a single value from a multi-value property, for example +ipv4.dns appends a resolver instead of replacing the list. After nmcli connection modify, the change is saved but not yet active; it takes effect after nmcli connection up or device reapply, which is a frequent source of confusion.

Common nmcli tasks

Most daily networking work can be done with a small set of commands. The examples below use placeholder names and addresses that would be adapted to a real network.

• List devices and state: nmcli device status shows each interface, its type and the active profile.
• Set a static address: nmcli connection modify office ipv4.method manual ipv4.addresses 192.0.2.10/24 ipv4.gateway 192.0.2.1.
• Join a Wi-Fi network: nmcli device wifi connect NETWORK password SECRET, which creates and activates a profile.
• Create a bridge: nmcli connection add type bridge ifname br0, then attach a port with type ethernet and the bridge as controller.
• Add a VLAN: nmcli connection add type vlan dev enp1s0 id 20 for tagged traffic on a trunk port.
• Script-friendly output: the -t terse and -f fields options produce stable output for parsing.

nmcli also manages bonds, teams, Linux bridge setups, WireGuard and VPN connections, which makes it the standard tool for building virtualization hosts on distributions where NetworkManager is the default.

nmcli compared with other Linux network tools

Several tools configure Linux networking, and choosing correctly depends on which daemon owns the interfaces on a given system. Mixing owners leads to settings being overwritten.

Netplan can use NetworkManager as its renderer, in which case nmcli shows the generated profiles, but edits should be made in the Netplan YAML so they are not lost on the next netplan apply. Firewall configuration is separate: firewalld zones can be tied to a profile with connection.zone, while nftables, iptables and UFW rules are managed by their own tools.

Pitfalls and good practice

Remote administration with nmcli carries one dominant risk: disconnecting the session that is used to make the change. Reactivating the profile of the interface that carries SSH traffic with a wrong address or gateway can lock the administrator out.

Safe practice includes using nmcli connection modify followed by nmcli device reapply where possible, keeping out-of-band console access ready, and testing changes with a scheduled rollback. Administrators should also check whether interfaces are marked as unmanaged, because NetworkManager ignores devices listed that way and nmcli changes then have no effect. Finally, DNS settings in resolv.conf may be generated by NetworkManager or systemd-resolved, so editing that file by hand is usually overwritten at the next connection change.

In everyday language

nmcli is a way to talk to the network manager of a Linux computer by typing instead of clicking. The network manager is like a building’s switchboard operator who knows which phone lines exist and how each should be connected.

With nmcli, you can tell that operator to use a fixed address, join a wireless network or create a new line, and the operator remembers the instructions, even after a restart. That memory is the main difference from tools that only change things until the next reboot.

Seen in the real world

A system administrator is preparing a Rocky Linux server to host virtual machines. The server has two network ports: one for management and one for guest traffic. Using nmcli, she creates a bridge named br0, attaches the second port to it, and sets the bridge to a static address with two DNS servers, all in four commands saved as persistent profiles.

Because she works over SSH on the management port, she leaves that profile untouched and verifies the bridge with nmcli device status and ip address before attaching any virtual machines. After a reboot test, the bridge comes up automatically and the guests reach the network on their own VLAN. The whole configuration is reproducible from a short script, which she stores in the team’s configuration repository.