The essentials
Quick reference
One focused task per row. Jump to the related section for complete, working examples.
| Use | Syntax | Examples |
|---|---|---|
| Show overall status | nmcli general status | View examples |
| List devices | nmcli device status | View examples |
| List active profiles | nmcli connection show --active | View examples |
| Inspect a profile | nmcli -f connection,ipv4,ipv6 connection show id \
'Office Wi-Fi' | View examples |
| List access points | nmcli -f IN-USE,SSID,BSSID,CHAN,RATE,SIGNAL,SECURITY \
device wifi list ifname wlp2s0 | View examples |
| Request a rescan | nmcli device wifi rescan ifname wlp2s0 | View examples |
| Connect with a prompt | nmcli --ask device wifi connect 'Office Wi-Fi' ifname \
wlp2s0 name 'Office Wi-Fi' | View examples |
| Activate using a secrets file | nmcli connection up id 'Office Wi-Fi' ifname wlp2s0 \
passwd-file /run/user/1000/nm-secrets | View examples |
| Activate by UUID | nmcli connection up uuid \
3f4f1df0-a596-4ca4-94be-31d6c0674c5e ifname wlp2s0 | View examples |
| Deactivate a profile | nmcli connection down uuid \
3f4f1df0-a596-4ca4-94be-31d6c0674c5e | View examples |
| Set autoconnect priority | sudo nmcli connection modify id 'Office Wi-Fi' \
connection.autoconnect yes \
connection.autoconnect-priority 20 | View examples |
| Configure static IPv4 | sudo nmcli connection modify id 'Office LAN' ipv4.method \
manual ipv4.addresses 192.0.2.20/24 ipv4.gateway \
192.0.2.1 | View examples |
| Set profile DNS | sudo nmcli connection modify id 'Office LAN' \
ipv4.ignore-auto-dns yes ipv4.dns \
'192.0.2.53 192.0.2.54' | View examples |
| Add a profile route | sudo nmcli connection modify id 'Office LAN' \
+ipv4.routes '198.51.100.0/24 192.0.2.1, 50' | View examples |
| Reload profiles | sudo nmcli connection reload | View examples |
| Reapply compatible settings | sudo nmcli device reapply wlp2s0 | View examples |
| Run under a checkpoint | sudo nmcli device checkpoint --timeout 60 wlp2s0 -- \
nmcli connection up id 'Office Wi-Fi' | View examples |
| Monitor changes | nmcli monitor | View examples |
| Read service logs | journalctl -u NetworkManager.service --since today \
--no-pager | View examples |
| Show nmcli version | nmcli --version | View examples |
NetworkManager separates persistent connection profiles from devices and their current activation state. Inspect both before changing anything: editing a profile does not necessarily alter the live device until reactivation, while disconnecting a remotely used interface can end your session immediately. Avoid passwords in command history, use UUIDs when profile names are ambiguous, and use a checkpoint or independent console for risky remote changes.
Step by step
Detailed examples
Distinguish devices, profiles, and active connections
A device is a network interface; a connection is stored configuration; an active connection is a profile applied to a device. Record all three plus NetworkManager permissions before remediation. A device may be unmanaged or controlled by another stack, and taking ownership can cause an outage.
nmcli general status
nmcli general permissions
nmcli device status
nmcli -t -f NAME,UUID,TYPE,DEVICE connection show
nmcli connection show --activeInspect profiles without leaking credentials
Profile names need not be unique, so scripts and changes should prefer UUIDs. Ordinary output hides stored secrets; --show-secrets exposes them and should be avoided in terminals, logs, tickets, and shared recordings. System profiles are commonly root-readable keyfiles, while user profiles have different visibility.
nmcli -f NAME,UUID,TYPE,DEVICE connection show
nmcli -f connection,802-11-wireless,802-11-wireless-security,ipv4,ipv6 connection show id 'Office Wi-Fi'Scan Wi-Fi deliberately
Scan results are observations, not trusted identity: duplicate SSIDs can belong to rogue access points. BSSID pinning limits roaming and can hurt resilience; hidden SSIDs offer no meaningful security and cause active probing. Confirm the expected enterprise authentication, CA trust, and server-name validation before entering credentials.
nmcli radio wifi
nmcli -f GENERAL,WIFI-PROPERTIES device show wlp2s0
nmcli device wifi rescan ifname wlp2s0
nmcli -f IN-USE,SSID,BSSID,CHAN,SIGNAL,SECURITY device wifi list ifname wlp2s0Keep Wi-Fi secrets out of process lists and history
A password typed as a command argument can be retained by shell history or exposed to local observers. Prefer --ask, a NetworkManager secret agent, or a mode-0600 passwd-file under a private runtime directory. For 802.1X, validate the CA and authentication server identity; disabling certificate validation enables credential theft.
nmcli --ask device wifi connect 'Office Wi-Fi' ifname wlp2s0 name 'Office Wi-Fi'
# For later activation, prompt through the active secret agent:
nmcli --ask connection up id 'Office Wi-Fi' ifname wlp2s0Activate the intended profile on the intended device
Activation can replace routes, DNS, addresses, and the default connection. Use UUID and ifname, check the resulting active state, and test both forward and return paths. Deactivation is immediately disruptive and does not delete the saved profile; deleting a profile is a separate persistent action.
nmcli connection up uuid 3f4f1df0-a596-4ca4-94be-31d6c0674c5e ifname wlp2s0
nmcli -f GENERAL,IP4,IP6,DHCP4,DHCP6 device show wlp2s0
ip route get 198.51.100.10Stage persistent changes and understand live application
connection modify changes the saved profile, but an active device may retain old settings. reapply supports only changes NetworkManager can safely apply live; otherwise reactivation is necessary and disruptive. Keep a profile export or exact prior values, avoid hand-editing keyfiles, and use connection reload after supported external edits.
nmcli -f connection.autoconnect,connection.autoconnect-priority connection show id 'Office Wi-Fi'
# Change only during an approved window:
# sudo nmcli connection modify id 'Office Wi-Fi' connection.autoconnect yes connection.autoconnect-priority 20
# sudo nmcli device reapply wlp2s0Treat DNS and routes as outage-sensitive settings
ignore-auto-dns suppresses DHCP DNS, so the replacement list must be reachable on every relevant path. Route syntax and policy support vary across NetworkManager versions. Check live routes, NetworkManager's view, the host resolver, VPN split-DNS behavior, and return paths before committing changes.
nmcli -f IP4.DNS,IP4.DOMAIN,IP4.ROUTE,IP4.GATEWAY device show wlp2s0
ip route show table all
resolvectl status wlp2s0
ip route get 192.0.2.53Protect remote changes with rollback
NetworkManager checkpoints can restore selected devices if a command fails or confirmation is not supplied, but availability and behavior are version-dependent. Use local or out-of-band access for critical systems and test checkpoint semantics first. Do not include an unrelated management interface unless it should roll back too.
nmcli --version
# Interactive and potentially disruptive; test locally first:
# sudo nmcli device checkpoint --timeout 60 wlp2s0 -- nmcli connection up id 'Office Wi-Fi'Correlate state, events, radio, and logs
A profile can fail because of RF conditions, driver or firmware errors, authentication, DHCP, routing, DNS, policy, or a captive portal. Start with narrow status and logs rather than enabling verbose logging indefinitely because debug output can contain identifiers and configuration details. Version-check properties before scripting them.
nmcli --version
nmcli networking connectivity check
nmcli monitor
# In a second terminal:
# journalctl -u NetworkManager.service --since '-10 minutes' --no-pagerSources and further reading
References
Authoritative documentation used to verify and expand this cheat sheet.
- NetworkManager Projectnmcli Reference Manualnetworkmanager.dev
- NetworkManager Projectnmcli Examplesnetworkmanager.dev
- NetworkManager ProjectNetworkManager Settings for nmclinetworkmanager.dev
- NetworkManager ProjectNetworkManager Keyfile Formatnetworkmanager.dev
- NetworkManager Project802.11 Wireless Settingnetworkmanager.dev
- NetworkManager Project802.11 Wireless Security Settingnetworkmanager.dev
Help us improve
Found a typo or missing example?
Tell us what would make this cheat sheet clearer, more complete, or more useful.