nmcli-agent

Register nmcli as a secret agent and listen for secret requests

$ nmcli [[a|agent]] [[s|secret]]

$ nmcli [[a|agent]] [[p|polkit]]

$ nmcli [[a|agent]] [[a|all]]

nmcli-agent [options]

--version
    Displays the version information of the nmcli-agent program.

--help
    Prints a brief help message detailing the command's usage and available options.

--register
    Registers this instance of the agent with NetworkManager. This action is usually handled automatically when the agent is started by a client needing its services.

The nmcli-agent is a crucial helper program within the NetworkManager framework. Its primary role is to serve as a secret agent, providing a graphical user interface when NetworkManager requires sensitive information from the user. For instance, when attempting to connect to a Wi-Fi network that demands a passphrase, or a VPN connection needing a password, nmcli-agent automatically launches.

It then presents a secure graphical dialog box—often leveraging underlying systems like libsecret or gnome-keyring—to prompt the user for the necessary credentials. This functionality is particularly vital for command-line NetworkManager clients like nmcli, which inherently lack the ability to display graphical prompts. By providing this interactive secret input mechanism, nmcli-agent ensures that network configuration remains user-friendly and secure, even when managed from the terminal. Users typically do not invoke it directly; it starts on demand when a secret is required by a client.

The nmcli-agent primarily provides a graphical secret prompt. This means it requires a graphical session and display server to function correctly. If running in a purely headless environment or without an active graphical session, it may not be able to display the prompt, and network connections requiring secrets might fail.

Users typically do not invoke nmcli-agent directly; it is an internal component launched by NetworkManager clients (like nmcli) when a secret is needed. Relying on other graphical components such as gnome-keyring or libsecret for backend secret storage is crucial for its operation.

The main purpose of nmcli-agent is to bridge the communication gap between NetworkManager's requirement for interactive secret input and the non-graphical nature of command-line tools like nmcli. It ensures that users can securely provide necessary credentials through a graphical prompt, even when managing network connections from the terminal, making the process seamless and secure.

Unlike many command-line utilities, nmcli-agent is rarely invoked directly by the user. Instead, it is automatically launched by NetworkManager clients (such as nmcli) whenever a network connection attempt necessitates a secret (e.g., a Wi-Fi password or VPN credentials) that is not already known or stored. This on-demand behavior ensures that the agent is only active when required, contributing to an efficient and user-friendly network setup experience.

nmcli-agent is an integral part of the NetworkManager project, which originated in 2004 with the goal of simplifying network configuration on Linux systems. As nmcli evolved into a robust command-line interface for NetworkManager, a clear need emerged for a mechanism to handle interactive secret requests—especially for sensitive data like Wi-Fi passphrases or VPN credentials that users might prefer not to pre-configure or store persistently. nmcli-agent was developed to address this gap, providing the necessary graphical prompts that a purely command-line tool like nmcli could not natively offer. Its integration ensures a consistent and secure method for users to supply network secrets across various NetworkManager clients, enhancing overall usability and security.

nmcli(1), NetworkManager(8), nm-applet(1), nmtui(1)