Safely inspect and connect an MBIM modem with mbimcli

You will use mbimcli to identify an MBIM modem, inspect its radio and registration state, and start or stop one data session without guessing at unsupported options. Allow about 15 minutes for a modem that is already attached to the host. The examples use /dev/cdc-wdm0 as a placeholder; replace it with the device path that exists on your machine.

1. Check the installed command and device path

This guide follows the installed mbimcli 1.31.2 from the libmbim-utils package. Its October 2025 manual page lists the Basic Connect commands used here. The exact response still depends on the modem firmware, SIM, network and MBIM features it exposes.

$ mbimcli --version
mbimcli 1.31.2
$ command -v mbimcli
/usr/bin/mbimcli
$ ls -l /dev/cdc-wdm0

If the last command fails, find the actual character device before doing anything else:

$ ls -l /dev/cdc-wdm*

Reading modem state normally needs no root shell, provided your account has permission to open the device. Do not add sudo automatically. If the device exists but access is denied, inspect its group and your group membership, then fix the host's device permissions through its normal policy.

2. Query capabilities without changing state

Start with a read-only capability query. The --device option selects the MBIM device, while --query-device-caps asks the modem what it supports.

$ mbimcli --device=/dev/cdc-wdm0 --query-device-caps

Expect a response containing modem-specific details such as device identifiers and supported services. Do not copy a particular response into a script as if it were universal. If the command cannot open the device, check the path and permissions first. If it opens but reports an unsupported operation, keep the error and use the modem's supported services as your boundary.

For a modem managed through the shared proxy, add --device-open-proxy:

$ mbimcli --device=/dev/cdc-wdm0 --device-open-proxy --query-device-caps

Use one opening method consistently while diagnosing a device. The proxy option requests mbim-proxy; it does not install or start that service for you.

Checkpoint: confirm the modem is usable

• mbimcli --version reports the installed version.
• The selected device path exists and your account can open it.
• The capability query returns a modem response rather than a path or permission error.

3. Read radio, SIM and registration state

These queries are safe starting points because they do not request a network session or change the modem. Run them separately so a failure identifies one operation clearly.

$ mbimcli --device=/dev/cdc-wdm0 --query-radio-state
$ mbimcli --device=/dev/cdc-wdm0 --query-pin-state
$ mbimcli --device=/dev/cdc-wdm0 --query-subscriber-ready-status
$ mbimcli --device=/dev/cdc-wdm0 --query-registration-state
$ mbimcli --device=/dev/cdc-wdm0 --query-signal-state
$ mbimcli --device=/dev/cdc-wdm0 --query-packet-service-state

Use the responses to separate common problems. A radio that is off is different from a SIM that is waiting for a PIN, and both are different from a modem that is powered and registered but has no packet service. The field names and values are supplied by the modem, so record the complete response when you need to ask an operator or vendor for help.

Do not test a PIN by guessing. --enter-pin, --change-pin, --enable-pin, --disable-pin and --enter-puk change security state or consume limited attempts. A wrong PUK can permanently block a SIM. Obtain the correct credential and confirm the PIN type before using one of those commands.

4. Register and attach only when required

If the modem is not registered, --register-automatic asks it to launch automatic registration. If the packet service is not attached, --attach-packet-service requests an attachment. Both actions affect the modem's network state and can take time.

$ mbimcli --device=/dev/cdc-wdm0 --register-automatic
$ mbimcli --device=/dev/cdc-wdm0 --query-registration-state
$ mbimcli --device=/dev/cdc-wdm0 --attach-packet-service
$ mbimcli --device=/dev/cdc-wdm0 --query-packet-service-state

Run the attach command only after checking the current state. A failure can mean no coverage, a blocked subscription, an unavailable data service or a modem-specific limitation. Do not repeatedly retry it in a tight loop while troubleshooting.

5. Connect one data session with explicit values

--connect accepts a quoted comma-separated list of key=value fields. The manual allows session-id, access-string, ip-type, auth, username, password, compression and context-type. The operator or SIM provider must supply the access string and any credentials. Do not paste real credentials into shell history or shared tickets.

$ mbimcli --device=/dev/cdc-wdm0 --connect="session-id=0,access-string=YOUR_APN,ip-type=ipv4v6"

This requests session 0 with an example access point name. Replace YOUR_APN with the value for your service. Add authentication fields only when the provider requires them, and treat the command line as sensitive if it contains a username or password.

After a successful response, query the session and its IP settings:

$ mbimcli --device=/dev/cdc-wdm0 --query-connection-state=0
$ mbimcli --device=/dev/cdc-wdm0 --query-ip-configuration=0
$ mbimcli --device=/dev/cdc-wdm0 --query-packet-statistics

A connected MBIM session is not the same thing as a configured host network interface. NetworkManager, ModemManager or another network service may own the next step. Avoid configuring the same interface from two managers, because they can disconnect or overwrite one another's state.

6. Disconnect and recover cleanly

Disconnecting is state-changing but reversible: it ends the selected data session. Use the same session ID that you connected, with session 0 as the documented default when no ID is supplied.

$ mbimcli --device=/dev/cdc-wdm0 --disconnect=0
$ mbimcli --device=/dev/cdc-wdm0 --query-connection-state=0

If a command fails after changing state, query the state before retrying. This avoids creating a second session or repeatedly sending an operation whose first request actually succeeded. If the device becomes unresponsive, stop competing modem managers before investigating, and use the host's normal service recovery procedure rather than repeatedly power-cycling hardware.

For diagnostics, --verbose adds debug logging. --verbose-full also includes personal information, so reserve it for a controlled terminal and redact its output before sharing it. --silent suppresses even error and warning logs, which makes it a poor choice while diagnosing a failure.