NVIDIA MLNX-OS CLI Guide: Modes and Commands

2026年8月26日 LOG admin

NVIDIA (Mellanox) MLNX-OS is the network operating system that runs on InfiniBand and Ethernet switches, with an industry-standard style CLI. This guide collects the core of the official user manual: the three CLI modes and how to move between them, syntax conventions, context help, include/exclude filtering, watch monitoring, json-print output and the keyboard shortcuts that make long sessions bearable. It is aimed at admins who are comfortable with a Cisco-style CLI and want to know exactly where MLNX-OS differs before they paste configuration into a production switch.

MLNX-OS is worth learning on its own terms rather than by analogy. The prompt shape is familiar, the editing keys are Unix-like, the filter modifiers are pipe-based - but the mode boundaries are stricter than IOS, the output modifiers are richer than IOS pipes, and every one of those modifiers is applied by the shell itself rather than by a Unix pipeline. Once the three modes and six modifiers are clear, the rest of the command tree reads like a well-organised man page.

CLI Modes

Mode	Prompt	Capability
Standard	switch >	Read-only, restricted set of status commands
Enable	switch #	All show commands plus operational actions (reset, reload, firmware), no configuration changes
Config	switch (config) #	Full configuration rights (admin role only)

switch > enable
switch # configure terminal
switch (config) # exit
switch # disable

The three modes form a single ladder, and the prompt tells you where you are at all times. Standard mode is what a new SSH session drops you into; it exposes a deliberately small command set so that a borrowed session cannot accidentally reconfigure a switch. Enable mode is where show becomes complete and where operational commands live - anything that changes the running state without changing the saved configuration, such as clearing counters or reloading the box. Config mode is the only place where configuration commands are accepted at all, and on MLNX-OS it is restricted to the admin role.

Two habits pay off immediately. First, read the prompt before typing, especially when working from a documented sequence whose commands assume a specific level - a command that "does not exist" in config mode often works fine one level up, and vice versa with configuration commands. Second, remember that nested configuration contexts exist inside config mode: entering an interface context changes the prompt to (config interface ethernet 1/1) #, and exit walks back one level at a time while end returns to config mode top level. Getting out of a deep context with the right command is faster than three guessed exits.

Prompt, Context and Command Behaviour

The bracket in the prompt is not decoration - it reflects real context, and commands are validated against it. A useful consequence: you can identify a misconfigured session from a screenshot, because the mode and, when in a context, the object being configured are both visible in the prompt string. MLNX-OS also supports a "do" style prefix in some contexts for running a show command without leaving the current context, which saves the round trip of exiting an interface to check counters and then re-entering it.

Commands are case-sensitive in MLNX-OS. show version works, Show Version does not, and the same applies to interface names, VLAN identifiers and usernames. The CLI accepts unambiguous abbreviations, so en resolves to enable and conf t resolves to configure terminal - but abbreviations that become ambiguous after a firmware upgrade start failing, which is one more reason to keep scripts in their fully spelled form.

Syntax and Help

Commands are case-sensitive; Tab completion and abbreviation are supported (en = enable). "?" shows the commands available in the current context, and <cr> indicates the command is already complete. The no form restores a parameter to its default value.

switch # sh?
  show         Show information
switch # show ?
  version      Show version information
  interfaces   Show interfaces information
switch # show version ?
  <cr>
switch # no cli default auto-logout
switch (config) # no interface ethernet 1/1 description

Read the ? output for the <cr> marker: it tells you the command will be accepted as typed, and a missing <cr> means a required argument is still outstanding. That single convention removes most "invalid parameter" guessing, because the CLI is telling you whether it wants more input before you press Enter.

The no form is the undo mechanism throughout the CLI. no plus a command restores its default, which is more reliable than trying to remember what the previous value was. Note that no is only available where the CLI documents it - some commands are one-way, particularly those that trigger an immediate action such as reloads or firmware writes.

Output Filtering and Monitoring

show interfaces ethernet status | include up
show power | exclude normal
show interfaces counters | watch diff interval 5
show ip interface | count
show version | json-print

watch refreshes at a fixed interval and highlights the diff (2-second default, Ctrl+C to exit); json-print emits show results as JSON (it cannot be combined with filtering or monitoring).

Four modifiers, four jobs. include keeps only lines matching a regular expression, which is how you turn a thousand-line port table into the four rows you care about. exclude is its inverse and is better for the case above: showing power information minus everything that is already nominal leaves only the abnormal. watch turns any show command into a live dashboard, and the diff highlighting is the important part - the difference between two samples is what tells you a counter is climbing versus merely large. count answers "how many" without making you read output at all, and json-print hands the raw structured result to a script.

Because these modifiers are implemented by the CLI rather than by a Unix shell, they cannot be chained arbitrarily the way pipes can. json-print in particular must be used on its own: ask for JSON, then filter it in your tooling, rather than trying to filter and serialise in one shot. Longer filter and watch recipes, including log-oriented workflows, are collected in MLNX-OS CLI filters, watch and link diagnostics.

Keyboard Shortcuts

Ctrl-a / Ctrl-e jump to the start / end of the line, Ctrl-w deletes the previous word, Ctrl-u deletes the whole line, Ctrl-k deletes from the cursor to the end of the line, Ctrl-l clears the screen, and Tab completes the current token.

The editing keys are Emacs-derived, which means muscle memory from a Unix shell transfers almost completely:

Ctrl-a - move to the beginning of the line; the fastest way to fix a wrong interface argument at the start of a long command.
Ctrl-e - move to the end of the line.
Ctrl-b / Ctrl-f - move back / forward one character.
Ctrl-w - delete the word before the cursor.
Ctrl-u - delete from the cursor to the beginning of the line; with the cursor at the end, this clears the whole line.
Ctrl-k - delete from the cursor to the end of the line.
Ctrl-l - clear the screen and redraw the prompt.
Ctrl-c - abort the command or the output currently being produced; the standard escape when a watch is running or a large show is scrolling.
Tab - complete the current token; if several commands share the prefix, Tab shows the alternatives instead of choosing for you.

Command history is available with the up and down arrows, and the history buffer is per-session - it does not survive a logout. On a switch where several people work, that is a feature: your last twenty commands are yours, not a shared shell history.

Session, Paging and Logging Commands

switch (config) # no cli default auto-logout
switch (config) # no cli session paging enable
switch # show cli
switch # cli clear-history
switch # show logging
switch # show logging files

Two of these are quality-of-life settings that pay for themselves immediately. Disabling auto-logout stops the session dying while you read a long output; disabling session paging keeps a large show from stopping at a page boundary, which is what makes copying output into a ticket practical. cli clear-history removes the session history, useful when a session has been shared on a screen. show logging is the first place to look after any change: MLNX-OS logs configuration attempts and failures, and the failed attempt often names the missing prerequisite that the error message did not.

Practical Recipes

! find every port that is down, without reading the whole table
show interfaces ethernet status | exclude Up

! watch a specific port's counters shifting in real time
show interfaces ethernet 1/1 counters | watch interval 3

! how many MAC entries are currently learned
show mac-address-table | count

! hand the routing table to a script
show ip route | json-print

! who else is logged in, and at which level
show users

! version and inventory in one pass for a support case
show version
show inventory

These five patterns - exclude for exception-hunting, watch for change detection, count for inventory questions, json-print for automation, show users for situational awareness - cover most of what a day-to-day CLI session requires. Everything else in MLNX-OS is command tree.

Common Mistakes in MLNX-OS Sessions

Four mistakes account for most broken sessions. Typing configuration commands in enable mode and concluding the feature does not exist, when the command is simply not visible until config mode. Forgetting configuration write after a successful change, which loses the work at the next reload. Using an abbreviation that is unambiguous today and ambiguous after the next firmware upgrade, which breaks a script nobody edited. And expecting shell features the CLI does not have: there is no redirection to a file, no command substitution, and filters cannot be chained the way Unix pipes can. If you need those, use | json-print and process the result on a management server rather than trying to build a pipeline inside the switch.

switch # configure terminal
switch (config) # no cli default auto-logout
switch (config) # configuration write
switch # show configuration files

Run show configuration files after any write if you are unsure whether the change reached startup-config; it is faster than reasoning about it, and it is the check that catches the one mistake in this list that costs real time.