SONiC CLI Commands: show, config and sonic-cli Modes

SONiC's command line confuses every engineer who comes from IOS or Junos, because there is no single monolithic CLI. In practice you work with three layers: Linux-style config commands that write into the Redis-backed config database, show commands that read state, and on many distributions a klish-based sonic-cli shell that emulates the familiar configure-terminal experience of traditional vendors. Understanding which layer you are in — and how configuration is persisted to config_db.json — is the real onboarding hurdle. This article explains each mode, how the prompts tell them apart, which commands belong in which mode, and how to read the output of the show commands you will type a hundred times a week.

Why SONiC Has Three Command Layers

The architecture explains the interface. SONiC's forwarding state is programmed by containers — swss and syncd talk to the ASIC, bgp runs FRR, teamd handles LAG — and every container reads its instructions from a Redis database. The CLI is therefore not the source of truth; it is a set of utilities that write keys into that database. Layer by layer:

• Layer 1 — the Linux shell. You are logged into Debian/Ubuntu, not a network OS CLI. Everything standard is available: ip, tcpdump, grep, pipelines, docker.
• Layer 2 — show commands. Read-only utilities that translate database and ASIC state into human-readable tables. Safe to run anywhere, anytime.
• Layer 3 — config commands. Wrappers around sonic-cfggen and the config database that apply changes. Usually need sudo.
• Layer 4 — sonic-cli (klish). An optional vendor-style shell laid over the same database, giving you configure terminal, interface sub-modes and a write save command.

The Linux Shell: Where You Actually Start

After logging in as admin you are dropped into a bash prompt, not a network CLI. That is a feature, not a rough edge: the same box lets you capture packets, count ports with a one-liner, and exec into containers.

admin@sonic:~$ show version
admin@sonic:~$ show uptime
admin@sonic:~$ docker ps
admin@sonic:~$ show int status | grep Eth | wc -l
admin@sonic:~$ sudo tcpdump -i Ethernet0 -c 10

Commands that modify system state need sudo, because the config database and the persistent files are owned by root. A config command that returns a permission error is not a bug — it is the shell telling you to add sudo. The sudo config form is the canonical one; typing config alone may work for read-ish operations and fail for writes.

The show and config Command Families

Nearly every SONiC operation is show <object> to inspect or config <object> to change, and subcommands can be abbreviated to their first three letters:

admin@sonic:~$ show version
admin@sonic:~$ show uptime
admin@sonic:~$ show interfaces status
admin@sonic:~$ show vlan brief
admin@sonic:~$ show ip bgp summary
admin@sonic:~$ show ip route
admin@sonic:~$ show lldp table

Configuration changes use the config family — for example VLANs and port-channels:

admin@sonic:~$ sudo config vlan add 10
admin@sonic:~$ sudo config vlan member add 10 Ethernet4
admin@sonic:~$ sudo config portchannel add PortChannel1
admin@sonic:~$ sudo config portchannel member add PortChannel1 Ethernet8
admin@sonic:~$ sudo config bgp add-neighbor 10.0.0.2
admin@sonic:~$ sudo config hostname dc-leaf-01

Notice the grammar. SONiC verbs are explicit and positional rather than modal: you do not enter a VLAN context and then add members, you issue config vlan member add 10 Ethernet4 as a single statement that enumerates what you want. That style is easier to script and easier to read in a change ticket, but it feels verbose coming from a modal CLI. Equally important, there is no candidate-versus-running concept here — the change takes effect as soon as the container reacts, so there is no commit to hide behind. The upside is that a mis-typed command either fails visibly or is trivially reversed with the matching del or remove form.

sonic-cli: The Configure-Terminal Experience

Distributions that ship sonic-cli (klish) provide a vendor-style shell on top of the same database. You enter it from the Linux shell and then move between modes exactly as you would on IOS:

admin@sonic:~$ sonic-cli
sonic# configure terminal
sonic(config)# interface ethernet 1
sonic(config-if-1)# ip address 30.1.1.2/24 30.1.1.1
sonic(config-if-1)# exit
sonic(config)# interface vlan 10
sonic(config-if-Vlan10)# exit
sonic(config)# exit
sonic# write save running-config

The prompts are the map:

The write save running-config command runs sonic-cfggen under the hood to dump the database back to disk — it is the klish equivalent of sudo config save -y, and it does not exist on every build. Note also the numbering difference: klish uses interface ethernet 1 while the Linux-level commands use Ethernet0. The port numbering and the exact feature set of sonic-cli both differ between distributions, so always verify what your image supports rather than assuming IOS parity. If a command that "should" work returns a syntax error, try the sudo config form before assuming the feature is missing.

Reading show Output: Three Commands Worth Mastering

Mode knowledge is only half the skill; the other half is interpreting what comes back.

show interfaces status

admin@sonic:~$ show interfaces status
  Interface        Lanes    Speed    MTU    FEC    Alias    Vlan    Oper    Admin    Type
  Ethernet0              0     100G   9100    rs         Eth1  routed      up       up    100GBASE-CR4
  Ethernet4              4     100G   9100    rs         Eth2  routed    down       up    100GBASE-CR4

Read the two state columns together and in that order. Admin is what you configured; Oper is what the hardware achieved. An up/up port is healthy, down/up means the link is enabled but not establishing — cable, optic, or speed mismatch — and down/down with Admin down means someone shut the port. Speed, MTU, FEC and the alias are all presented in the same row, which makes this one command the fastest way to spot a port that was never enabled or a lane count that does not match the breakout you expected.

show interfaces counters

admin@sonic:~$ show interfaces counters
    Interface            RX_OK            RX_BPS    RX_UTIL    RX_ERR    RX_DRP
    Ethernet0        123456789           1.2GB/s      12.3%         0         0
    Ethernet4                0              0 B/s       0.0%       145        12

The error and drop columns are where the diagnosis lives. RX_ERR at the physical layer means bits are arriving corrupted — FCS, runt or alignment failures — and points at the cable, the optic, or the connector. RX_DRP means the packet arrived intact and was discarded in the ingress pipeline, so look at ACLs, policies and buffer configuration instead. Seeing a non-zero and climbing RX_ERR on exactly one port in a bundle is the classic signature of a bad member link, and it is worth checking before you blame the ASIC or the software.

show bgp summary

admin@sonic:~$ show bgp summary
Neighbor        V    AS   MsgRcvd   MsgSent   TblVer  InQ OutQ  Up/Down  State/PfxRcd
10.0.0.2        4 65001     12345      12300       0    0    0  1d02h05m           42
10.0.0.6        4 65002         0          0       0    0    0    never       Active

Two things to check, always in this order. First the final column: a number means the session is established and that number is the count of prefixes received, whereas a word — Active, Idle, Connect — means the session is not up and the word itself tells you which TCP/BGP stage failed. Second, the InQ and OutQ columns: a non-zero input queue means the BGP process is not consuming updates fast enough and prefixes are about to be dropped. A session that reads Active with zero messages received is almost never a BGP policy problem; check reachability and the TCP/179 path first.

Persistence: config_db.json and the Redis Database

SONiC does not auto-persist. Changes live in the Redis config database (instance 4) until you save them, and a reload rebuilds everything from /etc/sonic/config_db.json:

admin@sonic:~$ sudo config save -y
admin@sonic:~$ sudo config reload -y
admin@sonic:~$ sudo config load /etc/sonic/config_db.json
admin@sonic:~$ sonic-cfggen -d --print-data
admin@sonic:~$ redis-cli -n 4 hgetall 'VLAN|Vlan10'

This is the mode distinction that matters most operationally: config save copies the live database to disk, config load merges a file into the live database, and config reload restarts services so they re-read from disk. config reload -y restarts almost all containers and interrupts traffic — schedule it in a maintenance window. Services run in containers, so deep troubleshooting means entering them:

admin@sonic:~$ docker ps
admin@sonic:~$ docker exec -it bgp sh
admin@sonic:~$ docker exec -it swss sh
admin@sonic:~$ show logging
admin@sonic:~$ show techsupport

Inside the bgp container you are in FRR, which is a genuinely modal CLI of the older school — vtysh then configure terminal — so within a single SONiC box you can end up working with two different CLI philosophies. Knowing which one you are in prevents the most common scripting mistake: putting vtysh commands in a Linux-level script or vice versa.

Help, Abbreviation and Completion

Three shell features make the mode model far easier to navigate. The ? character at any point in a command prints the available subcommands, and help or -h prints usage for a specific one:

admin@sonic:~$ config ?
admin@sonic:~$ config interface ?
admin@sonic:~$ config interface ip --help
admin@sonic:~$ show interfaces --help
admin@sonic:~$ sudo config --help

In the Linux layer, bash completion and the help subcommand are your documentation — there is no ? key that walks a tree the way Junos does. Inside klish-based sonic-cli, the question mark behaves as it does on a traditional NOS: typing ? at the sonic# prompt lists top-level commands and typing a partial command followed by ? lists the valid continuations. If ? returns a bash glob error instead of a command list, you are in the Linux shell, not in sonic-cli — a quick, unambiguous way to tell the two apart when the prompt has been misread.

Abbreviation is another source of confusion. The three-letter abbreviation rule applies to show and config subcommands, so show int status and show interfaces status are the same command, but abbreviations that collide are rejected rather than resolved arbitrarily. Do not rely on abbreviation inside scripts: write the full command so the next engineer, and the next OS release, both understand what you meant.

Which Mode Should You Use?

• Everyday verification: Linux shell with show commands.
• Configuration on a supported feature: sudo config ... from the Linux shell — it is scriptable, idempotent-ish and present on every distribution.
• Engineers who need vendor-style muscle memory: sonic-cli, but verify feature support first.
• Protocol-level work (route-maps, communities, timers): inside the bgp container via docker exec -it bgp vtysh.
• Anything not yet exposed by the CLI: write the key into Redis directly — and then save, because direct writes are even easier to lose than CLI changes.

Common Mistakes in Command Modes

• Forgetting sudo. A permission error is not a missing feature.
• Forgetting config save -y. The change works until the next reboot, then vanishes.
• Treating config load like a reload. Load merges into the running database; reload restarts services. They are not interchangeable.
• Assuming klish mirrors IOS. Port numbering, command names and available features all vary by distribution.
• Running config reload for a one-line change. A single interface IP change does not require restarting the whole box.

For the full daily-ops command set, keep our SONiC CLI cheat sheet and the show/config/docker quick reference open while you work, and for the whole install-to-operations path see the SONiC user manual. Our NVIDIA MLNX-OS CLI modes guide is a useful comparison if you also run that platform, since MLNX-OS keeps a more traditional mode hierarchy than SONiC.

原文链接：https://docs.asternos.com/routing/configuration-guide/first-use