1NMCLI(1) General Commands Manual NMCLI(1)
2
6 nmcli - command-line tool for controlling NetworkManager
7
9 nmcli [ OPTIONS ] OBJECT { COMMAND | help }
10 OBJECT := { nm | con | dev }
13 OPTIONS := {
16 -t[erse]
17 -p[retty]
18 -m[mode] tabular | multiline
19 -f[ields] <field1,field2,...> | all | common
20 -e[scape] yes | no
21 -v[ersion]
22 -h[elp]
23 }
24
27 nmcli is a command-line tool for controlling NetworkManager and getting
28 its status. It is not meant as a replacement of nm-applet or other
29 similar clients. Rather it's a complementary utility to these pro‐
30 grams. The main nmcli's usage is on servers, headless machines or just
31 for power users who prefer the command line.
32 The use cases comprise:
34 — Initscripts: ifup/ifdown can utilize NetworkManager via nmcli
36 instead of having to manage connections itself and possible inter‐
37 fere with NetworkManager.
38 — Servers, headless machines: No GUI is available; then nmcli is used
40 to talk directly to NetworkManager and control only system-wide
41 connections.
42 — User sessions: For this case, nmcli can talk to nm-applet to find
44 user connections. It can still talk directly to NetworkManager for
45 manipulating these connections. As nmcli doesn't have direct
46 access to user configuration data in GConf, nm-applet handles that
47 itself. That may, for example, cause the applet to pop up keyring
48 dialogs when secrets are needed.
49 OPTIONS
51 -t, --terse
52 Output is terse. This mode is designed and suitable for com‐
53 puter (script) processing.
54 -p, --pretty
56 Output is pretty. This causes nmcli to produce easy readable
57 outputs for humans, i.e. values are aligned, headers are
58 printed, etc.
59 -m, --mode tabular | multiline
61 Switch between tabular and multiline output. If omitted,
62 default is tabular for most commands. For the commands produc‐
63 ing more structured information, that cannot be displayed on a
64 single line, default is multiline. Currenly, they are:
65 'nmcli con list id|uuid <name>'
66 'nmcli dev list'
67 tabular - Output is a table where each line describes a single
68 entry. Columns define particular properties of the entry.
69 multiline - Each entry comprises more lines, each property on
70 its own line. The values are prefixed with the property name.
71 -f, --fields <field1,field2,...> | all | common
73 This option is used to specify what fields (column names) should
74 be printed. Valid field names differ for specific commands.
75 List available fields by providing an invalid value to the
76 --fields option.
77 all is used to print all valid field values of the command.
78 common is used to print common field values of the command. If
79 omitted, default is common. The option is mandatory when
80 --terse is used. In this case, generic values all and common
81 cannot be used. (This is to maintain compatibility when new
82 fields are added in the future).
83 -e, --escape yes | no
85 Whether to escape ':' and '\' characters in terse tabular mode.
86 The escape character is '\'. If omitted, default is yes.
87 -v, --version
89 Show nmcli version.
90 -h, --help
92 Print help information.
93 OBJECT
95 nm NetworkManager
96 Use this object to inquire and change state of NetworkManager.
97 COMMAND := { status | enable | sleep | wifi | wwan }
100 status
103 Show overall status of NetworkManager. This is the
104 default action, when no command is provided to nm object.
105 Reference to D-Bus:
106 No simple reference.
107 enable [true|false]
109 Get networking-enabled status or enable/disable network‐
110 ing by NetworkManager. All interfaces managed by Net‐
111 workManager are deactivated when networking has been dis‐
112 abled.
113 Reference to D-Bus:
114 interface: org.freedesktop.NetworkManager
115 method: Enable
116 arguments: TRUE or FALSE
117 sleep [true|false]
119 Get sleep status or put to sleep/awake NetworkManager.
120 All interfaces managed by NetworkManager are deactivated
121 when it falls asleep. This command is not meant for user
122 to enable/disable networking, use enable for that. D-Bus
123 Sleep method is designed to put NetworkManager to sleep
124 or awake for suspending/resuming computer.
125 Reference to D-Bus:
126 interface: org.freedesktop.NetworkManager
127 method: Sleep
128 arguments: TRUE or FALSE
129 wifi [on|off]
131 Inquire or set status of WiFi in NetworkManager. Without
132 any further argument, WiFi status is printed; on enables
133 WiFi; off disables WiFi.
134 Reference to D-Bus:
135 No simple reference.
136 wwan [on|off]
138 Inquire or set status of WWAN in NetworkManager. Without
139 any further argument, WWAN status is printed; on enables
140 WWAN; off disables WWAN.
141 Reference to D-Bus:
142 No simple reference.
143 con Connections
146 Get information about NetworkManager's connections.
147 COMMAND := { list | status | up | down }
150 list [id <id> | uuid <id> | system | user]
153 List configured connections. Without a parameter, con‐
154 figured connection from both system and user settings
155 services are listed. system argument filters only sys‐
156 tem-wide connections, user prints user connections only.
157 In order to get connection details, id with connection's
158 name or uuid with connection's UUID shall be specified.
159 When no command is given to con object, the default
160 action is 'nmcli con list'.
161 Reference to D-Bus:
162 No simple reference.
163 status
165 Print status of active connections.
166 Reference to D-Bus:
167 No simple reference.
168 up id <id> | uuid <id> [iface <iface>] [ap <hwaddr>] [--nowait]
170 [--timeout <timeout>]
171 Activate a connection. The connection is identified by
172 its name using id or UUID using uuid. For requiring par‐
173 ticular device to activate the connection on, iface
174 option with interface name should be given. ap option
175 can further concretize what AP should be used in case of
176 WiFi connection. --nowait option causes nmcli to exit
177 immediately and not to wait for command completion.
178 --timeout option provides a means to specify how long to
179 wait for operation completion.
180 Reference to D-Bus:
181 interface: org.freedesktop.NetworkManager
182 method: ActivateConnection
183 arguments: according to arguments
184 down id <id> | uuid <id>
186 Deactivate a connection. The connection is identified by
187 its name using id or UUID using uuid.
188 Reference to D-Bus:
189 interface: org.freedesktop.NetworkManager
190 method: DeactivateConnection
191 arguments: according to arguments
192 dev Devices
195 Get information about devices.
196 COMMAND := { status | list | disconnect | wifi }
199 status
202 Print status of devices. This is the default action,
203 when no command is specified to dev object.
204 Reference to D-Bus:
205 No simple reference.
206 list [iface <iface>]
208 Get detailed information about devices. Without an argu‐
209 ment, all devices are examined. To get information for a
210 specific device, iface argument with the interface name
211 should be provided.
212 Reference to D-Bus:
213 No simple reference.
214 disconnect iface <iface> [--nowait] [--timeout <timeout>]
216 Disconnect a device and prevent the device from automati‐
217 cally activating further connections without user/manual
218 intervention. --nowait option causes nmcli to exit imme‐
219 diately and not to wait for command completion. --time‐
220 out option provides a means to specify how long to wait
221 for operation completion.
222 Reference to D-Bus:
223 interface: org.freedesktop.NetworkManager.Device
224 method: Disconnect
225 arguments: none
226 wifi [list [iface <iface>] [hwaddr <hwaddr>]]
228 List available WiFi access points. iface and hwaddr
229 options can be used to get just APs for particular inter‐
230 face or specific AP, respectively.
231 Reference to D-Bus:
232 No simple reference.
233
236 nmcli's behavior is affected by the following environment variables.
237 LC_ALL If set to a non-empty string value, override the values of
239 all the other internationalization variables.
240 LC_MESSAGES Determines the locale to be used for internationalised
242 messages.
243 LANG Provides a default value for the internationalization
245 variables that are unset or null.
246 Notes about localization:
248 Be aware that nmcli is localized and that's why the output depends on
249 your environment. It's important to realize that especially when you
250 parse the output.
251 Call nmcli as LC_ALL=C nmcli to be sure the locale is set to "C" while
252 executing in a script.
253 LC_ALL, LC_MESSAGES, LANG variables specify the LC_MESSAGES locale cat‐
255 egory (in that order), which determines the language that nmcli uses
256 for messages. The "C" locale is used if none of these variables are
257 set, and this locale uses English messages.
258
261 nmcli exits with status 0 if it succeeds, a value greater than 0 is
262 returned if errors occur.
263 0 Success - indicates the operation succeeded
265 1 Unknown or unspecified error
267 2 Invalid user input, wrong nmcli invocation
269 3 Timeout expired (see commands with --timeout option)
271 4 Connection activation failed
273 5 Connection deactivation failed
275 6 Disconnecting device failed
277
280 There are probably some. If you find a bug, please report to
281 https://bugzilla.gnome.org/ - product NetworkManager.
282
285 nm-tool(1), nm-online(1), NetworkManager(8).
286 22 September 2010 NMCLI(1)