Connect to a Network Safely with nmtui-connect

You will use nmtui-connect to choose an existing NetworkManager connection, activate or deactivate it, and check the result from the shell. The installed command is part of NetworkManager 1.46.0, from package version 1.46.0-1ubuntu2.8 on this machine.

Allow about ten minutes for a familiar network and longer if you need to diagnose credentials or device state. You need a terminal with a working text interface, NetworkManager, and an existing connection profile or a visible Wi-Fi network. Most checks are unprivileged. NetworkManager may ask for authorisation when the connection or device policy requires it.

1. Confirm the installed command

Check the executable and package before opening the interface. These are read-only commands and do not need sudo:

$ command -v nmtui-connect
/usr/bin/nmtui-connect
$ dpkg-query -W -f='${Package} ${Version}\n' network-manager
network-manager 1.46.0-1ubuntu2.8
$ nmtui-connect --help
Usage:
  nmtui-connect [OPTION...]

Help Options:
  -h, --help       Show help options

The command's main job is interactive, so --help only shows the help option. The manual describes the same activity as nmtui connect. The separate nmtui-connect binary is a shortcut that skips the activity-selection screen.

2. Check NetworkManager before changing anything

Record the current device state with nmcli. This gives you a before-and-after comparison and helps distinguish a failed selection from a disconnected cable, disabled radio, or unavailable access point:

$ nmcli device status
DEVICE   TYPE      STATE                   CONNECTION
enp1s0   ethernet  connected               Office wired
wlp2s0   wifi      disconnected             --
lo       loopback  connected (externally)   --

Your devices and columns may differ. The useful facts are the device name, its state, and the active connection name. If NetworkManager is not running, repair that service through your normal system-management process before using the interface. Do not treat a missing connection as a reason to guess a profile name.

3. Open the connection list

Start the text interface:

$ nmtui-connect

It displays available NetworkManager connections and provides controls to activate or deactivate them. The list is host-specific. A connection profile is not the same thing as a physical device: one device can have several profiles, while a profile may only be usable on a compatible device.

Use the terminal's normal cursor and selection controls, then choose the existing connection you intend to use. Read the complete name before activating it. Similar names such as Office, Office guest, and Office VPN are easy to confuse.

For a quick launch into a specific target, the documented forms accept a connection name, UUID, device name, or Wi-Fi SSID:

$ nmtui-connect "Office wired"
$ nmtui-connect wlp2s0
$ nmtui-connect "Example Wi-Fi"

Use one form at a time and quote names containing spaces. If the target is ambiguous or is not found, omit the argument and choose from the displayed list instead. The command does not create a missing profile merely because you supplied a name.

4. Activate one connection

Select the intended connection and use the interface's activate control. For Wi-Fi, NetworkManager may request credentials or authorisation. Enter a password only into the prompt you intentionally opened; do not put it in a shell command or paste it into a support transcript.

After the interface reports success, exit back to the shell and verify the resulting state:

$ nmcli device status
DEVICE   TYPE      STATE      CONNECTION
wlp2s0   wifi      connected  Example Wi-Fi
enp1s0   ethernet  unavailable --

The exact output varies. Check that the expected device says connected and names the expected profile. A successful activation does not prove that the network provides Internet access, only that NetworkManager activated the connection.

5. Test the connection without changing it

Ask NetworkManager for its active connection summary:

$ nmcli connection show --active
NAME           UUID                                  TYPE      DEVICE
Example Wi-Fi  11111111-2222-3333-4444-555555555555  wifi      wlp2s0

Do not copy the example UUID as a real value. Compare the name and device with the result from nmcli device status. If you need an application-level check, use a destination and tool appropriate to your environment. A DNS lookup or a request to an approved internal service can be more useful than assuming that an active profile means unrestricted Internet access.

6. Deactivate a connection when you need to undo it

Return to nmtui-connect, select the active connection, and choose its deactivate control. This stops that connection; it does not delete the saved profile. Verify the result from the shell:

$ nmcli device status
DEVICE   TYPE  STATE          CONNECTION
wlp2s0   wifi  disconnected   --

If you lost your route or remote session, reconnect using the previous working profile, a local console, or your normal out-of-band access. If the connection was only temporarily needed, deactivation is the undo action. Do not remove a profile as a first response to a failed activation: deletion is a separate, destructive configuration change and is not part of nmtui-connect.

7. Diagnose the common failures

If the expected profile is absent, first confirm that NetworkManager sees the device and that the profile exists. Listing profiles is read-only:

$ nmcli connection show
NAME              UUID                                  TYPE      DEVICE
Office wired      66666666-7777-8888-9999-000000000000  ethernet  enp1s0
Example Wi-Fi     11111111-2222-3333-4444-555555555555  wifi      --

A profile with -- in the device column is saved but inactive. If a Wi-Fi network is not offered, check radio state and scan visibility with your normal NetworkManager tools. A hidden SSID, distance, blocked radio, or incompatible security settings can all prevent activation.

If activation fails, record the message and recheck nmcli device status. Look for a non-connected state, a different active profile, or an authorisation prompt that was cancelled. Do not repeatedly enter a password when the error indicates a policy or device problem. For a service-disrupting change, restore the last known working connection rather than experimenting with several profiles at once.