Inspect NetworkManager Safely with nmcli

You will finish with a small, repeatable workflow for checking NetworkManager, identifying devices and active connection profiles, and extracting values for scripts without exposing passwords. The examples match NetworkManager 1.46.0 and nmcli 1.46.0, from Ubuntu package version 1.46.0-1ubuntu2.8.

Allow about fifteen minutes. You need a shell and the network-manager package. The first half is read-only and normally needs no elevated privileges. The final section describes changes but does not ask you to make one. Network names, interface names and connection states are host-specific, so treat sample output as a shape to recognise rather than text to copy literally.

1. Confirm the installed tool

Start with version and help output. These commands query the local installation and do not change networking:

$ nmcli --version
nmcli tool, version 1.46.0
$ dpkg-query -W -f='${Package} ${Version}\n' network-manager
network-manager 1.46.0-1ubuntu2.8
$ nmcli --help | sed -n '1,24p'
Usage: nmcli [OPTIONS] OBJECT { COMMAND | help }

The main objects are general, networking, radio, connection, device, agent and monitor. Subcommands can be abbreviated, but full names are easier to review in shell history and automation.

2. Get the three useful status views

Check the daemon's view of overall state, then check devices and active profiles:

$ nmcli general status
STATE         CONNECTIVITY  WIFI-HW  WIFI     WWAN-HW  WWAN
connected     full          enabled  enabled  missing  enabled
$ nmcli device status
DEVICE   TYPE      STATE      CONNECTION
enp0s31f6 ethernet  connected  Office LAN
lo       loopback  connected  lo
$ nmcli connection show --active
NAME       UUID                                  TYPE      DEVICE
Office LAN 11111111-2222-3333-4444-555555555555 ethernet  enp0s31f6

Your output may say disconnected, unknown or unmanaged. That is evidence about this host, not a command failure. device status reports devices; connection show reports saved profiles, which may be inactive. NetworkManager can hold several profiles that apply to one device, while only one is active on that device.

For a fresh connectivity check rather than the last known result, use:

$ nmcli networking connectivity check
full

The possible states are none, portal, limited, full and unknown. A captive portal can therefore look different from a completely disconnected machine.

3. Inspect a device without displaying secrets

Use the interface name from your own device listing. This is read-only:

$ nmcli device show enp0s31f6
GENERAL.DEVICE:                         enp0s31f6
GENERAL.TYPE:                           ethernet
GENERAL.STATE:                          100 (connected)
GENERAL.CONNECTION:                     Office LAN
IP4.ADDRESS[1]:                         192.0.2.42/24
IP4.GATEWAY:                            192.0.2.1
IP4.DNS[1]:                             192.0.2.53

Real addresses and fields depend on the device. Do not add --show-secrets casually: that global option permits passwords and other connection secrets to appear in output. Avoid saving such output in tickets, shell transcripts or CI logs.

To inspect the saved profile itself, use an unambiguous ID. A connection name can contain spaces:

$ nmcli connection show id 'Office LAN'
connection.id:                          Office LAN
connection.type:                        802-3-ethernet
ipv4.method:                            auto

If a name is ambiguous, use uuid followed by the UUID from connection show. The profile view normally combines stored configuration with active data; use --active when you need only active information.

4. Produce stable values for a script

Human-oriented tables are useful at a terminal but awkward to parse. The -g option is a shortcut for terse, tabular, selected fields and prints values without headings:

$ nmcli -g NAME,TYPE,DEVICE connection show --active
Office LAN:802-3-ethernet:enp0s31f6

Use --terse and --fields when you need the individual controls to be obvious:

$ nmcli --terse --escape yes --fields DEVICE,TYPE,STATE device status
enp0s31f6:ethernet:connected

Terse mode escapes separators in values by default. That matters when a connection name contains a colon or backslash. For scripts, check the exit status and quote the result as data; do not turn it into shell code. For example:

$ state=$(nmcli -g GENERAL.STATE device show enp0s31f6) || {
>   printf '%s\n' 'could not query the device' >&2
>   exit 1
> }
$ printf 'state: %s\n' "$state"
state: 100 (connected)

5. Understand commands that change state

Read-only inspection does not require sudo in the normal case. These commands do change the host and can interrupt service:

• nmcli connection up ID activates a saved profile. Without --wait, the documented default timeout for activation is 90 seconds.
• nmcli connection down ID deactivates an active profile, but the device can still auto-activate another suitable profile.
• nmcli networking off disables NetworkManager networking and deactivates all interfaces it manages.
• nmcli radio wifi off disables Wi-Fi through NetworkManager.

$ nmcli connection up id 'Office LAN' ifname enp0s31f6
Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/7)
$ nmcli connection show --active

The active path is variable. If the profile was edited rather than merely activated, there is no universal undo command: restore the previous property values from a recorded nmcli connection show id 'Office LAN' result, then activate the profile if required. Take that backup before changing a production connection.

6. Diagnose the common traps

An empty active-profile list does not mean that saved profiles are absent. Compare both views:

$ nmcli connection show
$ nmcli connection show --active

If a device is unmanaged, changing a profile will not make NetworkManager control it. Check the owning service or policy before trying more nmcli commands. If an activation needs a password, --ask permits an interactive prompt; do not use it in a non-interactive script. A password file can supply credentials, but it is sensitive and must have permissions and a lifetime appropriate to the host.

When a command appears to hang during activation, use an explicit wait value such as --wait 30 for a bounded operation. A wait of 0 returns immediately and does not mean that activation has completed, so verify afterwards with nmcli connection show --active.