nmcli 1.7.0
A python wrapper library for the network-manager cli client
Requires Python: >=3.7

# nmcli

nmcli is a python wrapper library for the network-manager cli client.

## Quick Sample

Here is a simple usecase.

```python
import nmcli

try:
    print(nmcli.connection())
    print(nmcli.device())
    print(nmcli.device.wifi())
    print(nmcli.general())

    nmcli.device.wifi_connect('AP1', 'passphrase')
    nmcli.connection.modify('AP1', {
            'ipv4.addresses': '192.168.1.1/24',
            'ipv4.gateway': '192.168.1.255',
            'ipv4.method': 'manual'
        })
    nmcli.connection.down('AP1')
    nmcli.connection.up('AP1')
    nmcli.connection.delete('AP1')
except Exception as e:
    print(e)
```

## Dependency

- NetworkManager
  - `sudo apt install network-manager` (Debian)
- User who can execute nmcli with sudo with NOPASSWD
  - If sudo is not needed (like root user), use `disable_use_sudo` at the beginning of the process.

## Compatibility table

| Object     | Command      | Status        |
| ---------- | ------------ | ------------- |
| general    |              | supported     |
| general    | status       | supported     |
| general    | hostname     | supported     |
| general    | permissions  | not supported |
| general    | logging      | not supported |
| general    | reload       | supported     |
| networking |              | supported     |
| networking | on           | supported     |
| networking | off          | supported     |
| networking | connectivity | supported     |
| radio      |              | supported     |
| radio      | all          | supported     |
| radio      | wifi         | supported     |
| radio      | wwan         | supported     |
| connection |              | supported     |
| connection | show         | supported     |
| connection | up           | supported     |
| connection | down         | supported     |
| connection | add          | supported     |
| connection | modify       | supported     |
| connection | clone        | not supported |
| connection | edit         | not supported |
| connection | delete       | supported     |
| connection | monitor      | not supported |
| connection | reload       | supported     |
| connection | load         | not supported |
| connection | import       | not supported |
| connection | export       | not supported |
| device     |              | supported     |
| device     | status       | supported     |
| device     | show         | supported     |
| device     | set          | not supported |
| device     | up           | supported     |
| device     | connect      | supported     |
| device     | reapply      | supported     |
| device     | modify       | not supported |
| device     | down         | supported     |
| device     | disconnect   | supported     |
| device     | delete       | supported     |
| device     | monitor      | not supported |
| device     | wifi                | supported     |
| device     | wifi connect        | supported     |
| device     | wifi rescan         | supported     |
| device     | wifi hotspot        | supported     |
| device     | wifi show-password  | not supported |
| device     | lldp                | not supported |
| agent      |              | not supported |
| agent      | secret       | not supported |
| agent      | polkit       | not supported |
| agent      | all          | not supported |
| monitor    |              | not supported |

## API

### connection

#### nmcli.connection

Get a list of connections.

```
nmcli.connection() -> List[Connection]
```

#### nmcli.connection.add

Create a new connection using specified properties.

```
nmcli.connection.add(
    conn_type: str,
    options: Optional[ConnectionOptions] = None,
    ifname: str = "*",
    name: str = None,
    autoconnect: bool = None) -> None
```

#### nmcli.connection.modify

Add, modify or remove properties in the connection profile.

```
nmcli.connection.modify(name: str, options: ConnectionOptions) -> None
```

#### nmcli.connection.delete

Delete a configured connection.

The `wait` argument applies the same effect to the command as the `--wait` option. If it is omitted, the default behavior is followed.

```
nmcli.connection.delete(name: str, wait: int = None) -> None
```

#### nmcli.connection.up

Activate a connection.

The `wait` argument applies the same effect to the command as the `--wait` option. If it is omitted, the default behavior is followed.

```
nmcli.connection.up(name: str, wait: int = None) -> None
```

#### nmcli.connection.down

Deactivate a connection from a device without preventing the device from further auto-activation.

The `wait` argument applies the same effect to the command as the `--wait` option. If it is omitted, the default behavior is followed.

```
nmcli.connection.down(name: str, wait: int = None) -> None
```

#### nmcli.connection.show

Show details for specified connections.

Use `show_secrets` argument to reveal associated secrets as well.
Use `active` argument to show only the active profile.

```
nmcli.connection.show(name: str, show_secrets: bool = False, active: bool = False) -> ConnectionDetails
```

#### nmcli.connection.show_all

Show all connections.

Use `active` argument to show only active connections.

```
nmcli.connection.show_all(active: bool = False) -> List[Connection]
```

#### nmcli.connection.reload

Reload all connection files from disk.

```
nmcli.connection.reload() -> None
```

### device

#### nmcli.device

Print status of devices.

```
nmcli.device() -> List[Device]
```

#### nmcli.device.status

Show status for all devices.

```
nmcli.device.status() -> List[Device]
```

#### nmcli.device.show

Show details of device.

The `fields` argument applies the same effect to the command as the `-f | --fields` option. If it is omitted, the default behavior is followed.

```
nmcli.device.show(ifname: str, fields: str = None) -> DeviceDetails
```

#### nmcli.device.show_all

Show details of devices.

The `fields` argument applies the same effect to the command as the `-f | --fields` option. If it is omitted, the default behavior is followed.

```
nmcli.device.show_all(fields: str = None) -> List[DeviceDetails]
```

#### nmcli.device.up

Connect the device.

The `wait` argument applies the same effect to the command as the `--wait` option. If it is omitted, the default behavior is followed.

```
nmcli.device.up(ifname: str, wait: int = None) -> None
```

#### nmcli.device.connect

Connect the device.

The `wait` argument applies the same effect to the command as the `--wait` option. If it is omitted, the default behavior is followed.

```
nmcli.device.connect(ifname: str, wait: int = None) -> None
```

#### nmcli.device.down

Disconnect a device and prevent the device from automatically activating further connections without user/manual intervention.

The `wait` argument applies the same effect to the command as the `--wait` option. If it is omitted, the default behavior is followed.

```
nmcli.device.down(ifname: str, wait: int = None) -> None
```

#### nmcli.device.disconnect

Disconnect devices.

The `wait` argument applies the same effect to the command as the `--wait` option. If it is omitted, the default behavior is followed.

```
nmcli.device.disconnect(ifname: str, wait: int = None) -> None
```

#### nmcli.device.reapply

Attempts to update device with changes to the currently active connection made since it was last applied.

```
nmcli.device.reapply(ifname: str) -> None
```

#### nmcli.device.delete

Delete the software devices.

The `wait` argument applies the same effect to the command as the `--wait` option. If it is omitted, the default behavior is followed.

```
nmcli.device.delete(ifname: str, wait: int = None) -> None
```

#### nmcli.device.wifi

List available Wi-Fi access points.

```
nmcli.device.wifi(ifname: str = None, rescan: bool = None) -> List[DeviceWifi]
```

#### nmcli.device.wifi_connect

Connect to a Wi-Fi network specified by SSID or BSSID.

The `wait` argument applies the same effect to the command as the `--wait` option. If it is omitted, the default behavior is followed.

```
nmcli.device.wifi_connect(ssid: str,
                          password: str,
                          ifname: str = None,
                          wait: int = None) -> None
```

#### nmcli.device.wifi_hotspot

Create a Wi-Fi hotspot

```
nmcli.device.wifi_hotspot(ifname: str = None,
                          con_name: str = None,
                          ssid: str = None,
                          band: str = None,
                          channel: int = None,
                          password: str = None) -> Hotspot
```

#### nmcli.device.wifi_rescan

Request that NetworkManager immediately re-scan for available access points.

```
nmcli.device.wifi_rescan(ifname: str = None, ssid: str = None) -> None
```

### general

#### nmcli.general

Show overall status of NetworkManager.

```
nmcli.general() -> General
```

#### nmcli.general.status

Show overall status of NetworkManager.

```
nmcli.general.status() -> General
```

#### nmcli.general.get_hostname

Get persistent system hostname.

```
nmcli.general.get_hostname() -> str
```

#### nmcli.general.set_hostname

Change persistent system hostname.

```
nmcli.general.set_hostname(hostname: str) -> None
```

#### nmcli.general.reload

Reload NetworkManager's configuration and perform certain updates.

The `flags` argument specifies which configurations to reload. Valid flags are:
- `conf`: Reload NetworkManager.conf configuration from disk
- `dns-rc`: Update DNS configuration (equivalent to SIGUSR1)
- `dns-full`: Restart the DNS plugin

If no flags are provided, everything that is supported is reloaded.

```
nmcli.general.reload(flags: Optional[List[str]] = None) -> None
```

### networking

#### nmcli.networking

Get network connectivity state.

```
nmcli.networking() -> NetworkConnectivity
```

#### nmcli.networking.on

Switch networking on.

```
nmcli.networking.on() -> None
```

#### nmcli.networking.off

Switch networking off.

```
nmcli.networking.off() -> None
```

#### nmcli.networking.connectivity

Get network connectivity state.

The optional 'check' argument makes NetworkManager re-check the connectivity.

```
nmcli.networking.connectivity(check:bool = False) -> NetworkConnectivity
```

### radio

#### nmcli.radio

Get status of all radio switches.

```
nmcli.radio() -> Radio
```

#### nmcli.radio.all

Get status of all radio switches.

```
nmcli.radio.all() -> Radio
```

#### nmcli.radio.all_on

Turn on all radio switches.

```
nmcli.radio.all_on() -> None
```

#### nmcli.radio.all_off

Turn off all radio switches.

```
nmcli.radio.all_off() -> None
```

#### nmcli.radio.wifi

Get status of Wi-Fi radio switch.

```
nmcli.radio.wifi() -> bool
```

#### nmcli.radio.wifi_on

Turn on Wi-Fi radio switches.

```
nmcli.radio.wifi_on() -> None
```

#### nmcli.radio.wifi_off

Turn off Wi-Fi radio switches.

```
nmcli.radio.wifi_off() -> None
```

#### nmcli.radio.wwan

Get status of mobile broadband radio switch.

```
nmcli.radio.wwan() -> bool
```

#### nmcli.radio.wwan_on

Turn on mobile broadband radio switches.

```
nmcli.radio.wwan_on() -> None
```

#### nmcli.radio.wwan_off

Turn off mobile broadband radio switches.

```
nmcli.radio.wwan_off() -> None
```

### other

#### nmcli.disable_use_sudo

Disable the use of sudo.

```
nmcli.disable_use_sudo() -> None
```

#### nmcli.set_lang

Change the environment variable LANG from the default `C`.
Run this command when you want to use `C.UTF-8`.

```
nmcli.set_lang(lang: str) -> None
```

## Change Log

### 1.7.0

- Added `nmcli.connection.show_all` method with active filtering support
- Added `nmcli.device.up` and `nmcli.device.down` methods
- Added `nmcli.general.reload` method with configuration flags support

### 1.6.0

- Added active option to `nmcli.connection.show`

### 1.5.0

- Added show_secrets option to `nmcli.connection.show`

### 1.4.0

- Supported unsupported cases of `DeviceWifi.parse`.
- Fixed the problem that `nmcli.general` does not work on nmcli client after version 1.48.x.

### 1.3.0

- Added rescan parameter to `nmcli.device.wifi`.

### 1.2.0

- Added support for encodings other than UTF-8.

### 1.1.2

- Fixed a problem with environment variables being scraped.

### 1.1.1

- Include LICENSE.txt in the tar.

### 1.1.0

- Added fields option to `nmcli.device.show` and `nmcli.device.show_all`

### 1.0.0

- Handle connection failure exceptions with `nmcli.device.wifi_connect`.
- Added wait param to `nmcli.connection.delete`, `nmcli.connection.up`, `nmcli.connection.down`, `nmcli.device.connect`, `nmcli.device.disconnect`, `nmcli.device.delete`, `nmcli.device.wifi_connect`.

### 0.9.0

- Added ifname param to wifi.

### 0.8.0

- Added support for changing the LANG environment variable.

### 0.7.0

- Added ifname param to wifi_connect.

### 0.6.1

- Fixed a bug in the autoconnect parameter of the nmcli.connection.add method (made the default value conform to the specification of nmcli connection add).

### 0.6.0

- Added BSSID and FREQ to DeviceWifi.

### 0.5.0

- Added support for "nmcli device wifi hotspot".
- Added support for "nmcli device wifi rescan".

### 0.4.2

- Fixed the parsing of device wifi.

### 0.4.1

- Fixed parsing when SSID has a space.

### 0.4.0

- Added disabling of sudo usage.
- Added support for parsing the execution results of recent versions of the nmcli device wifi command.

### 0.3.1

- Fixed device status and device wifi parsing bug.

### 0.3.0

- Added networking and radio APIs.
- Added more APIs for connection, device and general.
- Changed the properties of the General data class.
- Changed throw a ValueError exception if the regular expression pattern is not matched.

### 0.2.2

- Fix the parsing bug of connection names that contain spaces (connection.show).
- Added getting items that begin with a capital letter.

### 0.2.1

- Fix the parsing bug of connection names that contain spaces.

### 0.2.0

- Added dummy classes.

### 0.1.0

- Initial release.

## License

MIT