Inspect and Operate Modems Safely with mmcli

mmcli is your window into ModemManager: it finds a modem, inspects its details and state, and can enable, disable or connect it. This guide walks through all of that and flags exactly which commands interrupt service. The examples match ModemManager 1.23.4 and its installed mmcli(1) manual. Allow about fifteen minutes if the modem is already connected to the machine.

You need a Linux shell, the modemmanager package, and a modem managed by ModemManager for the device-specific steps. The first checks are read-only and normally need no elevated privileges. Enabling, disabling, registering or connecting a modem may be restricted by the machine's authorisation policy. Use sudo only when your system administrator explicitly requires it, and remember that sudo does not make an absent modem appear.

1. Confirm the installed command and daemon

Start with the binary and package version. This is an ordinary, read-only checkpoint:

$ command -v mmcli
/usr/bin/mmcli
$ dpkg-query -W -f='${Package} ${Version}\n' modemmanager
modemmanager 1.23.4-0ubuntu2
$ mmcli --version
mmcli 1.23.4

Ask the running daemon for its version with -B. The version is a property of the daemon currently running, not merely of the installed package:

$ mmcli -B
ModemManager daemon 1.23.4 running

If this reports that the daemon is unavailable, stop at this checkpoint. Investigate the service with your normal service-management tools before trying modem operations. Do not start changing modem settings to solve a daemon problem.

2. List the available modems

Use -L to list modems that the daemon currently knows about:

$ mmcli -L
    /org/freedesktop/ModemManager1/Modem/0 [Example Mobile] Example LTE Modem

The path, vendor and index are host-specific. On a machine with no managed device, the installed command prints:

$ mmcli -L
    No modems were found

Do not copy the example index blindly. Record the number at the end of your own path, or use the complete object path. Checkpoint: you have either found a modem identifier or established that there is no modem for the next steps to inspect.

3. Inspect one modem before changing it

Replace MODEM_INDEX with the index from mmcli -L. With no action option, mmcli shows the default information for the selected modem:

$ mmcli --modem MODEM_INDEX

The fields and values depend on the modem and its capabilities, so do not script against an example display. Treat the output as inspection, not as proof that a data connection is active. In particular, a registered modem can still lack a bearer, and a modem with a SIM may still need a PIN.

For a live state watch, run:

$ mmcli --modem MODEM_INDEX --monitor-state

This command stays attached while the modem changes state. Press Ctrl+C to stop watching. Stopping this monitor does not disable the modem or disconnect it.

4. Enable or disable only with an explicit reason

--enable powers the antenna and begins automatic registration. --disable disconnects existing connections and places the modem into a low-power mode. Both are state-changing operations, so check the modem details first and warn anyone relying on the connection:

$ mmcli --modem MODEM_INDEX --enable
$ mmcli --modem MODEM_INDEX
$ mmcli --modem MODEM_INDEX --disable

Do not run the final command as a casual test. It interrupts service. The recovery is the corresponding --enable command, followed by the normal registration or connection workflow for that modem. If the modem is managed by another connection manager, let that manager control the lifecycle rather than competing with it through mmcli.

5. Connect only after checking the bearer details

The simple connection operation combines the connection sequence into one command. For a 3GPP modem, the manual documents an APN key; use the APN supplied by the network operator:

$ mmcli --modem MODEM_INDEX --simple-connect="apn=APN_FROM_PROVIDER"
$ printf 'exit status: %s\n' "$?"
exit status: 0

Replace APN_FROM_PROVIDER with a real value. Do not guess an APN, PIN, username or password. A connection can incur charges or select a roaming network, depending on the SIM and operator. The command may create or activate a bearer and change routing outside mmcli's output.

To disconnect all connected bearers for that modem, use the matching operation:

$ mmcli --modem MODEM_INDEX --simple-disconnect
$ printf 'exit status: %s\n' "$?"
exit status: 0

This is also service-disrupting. Run it only when you intend to end every bearer for the selected modem, not merely one application flow. If the command fails, inspect the modem again and check which connection manager owns it before retrying.

6. Diagnose the common traps

• No modems found: check the cable, power, USB enumeration and whether the device is supported. mmcli -L can only list devices already detected by ModemManager.
• Wrong modem: use the complete object path from mmcli -L instead of assuming index 0. Indexes are assigned by the daemon and are not a permanent device name.
• Permission denied: check the desktop or system authorisation policy. Adding sudo may alter which user and policy are involved, but it does not fix a missing policy or a modem owned by another manager.
• Connection fails: verify registration, SIM readiness and the operator's APN. Avoid repeatedly trying guessed credentials, especially the SIM PIN.
• Commands appear to hang: --monitor-state is deliberately long-running. Inhibition commands also remain attached until you press Ctrl+C; stopping them removes the inhibition.