SONiC CLI Cheat Sheet: Show, Config and Config-DB Commands

SONiC (Software for Open Networking in the Cloud) has a layered management model that confuses engineers coming from traditional switch CLIs: a Klish-based CLI shell, a set of config commands, a Redis-backed Config-DB, and Linux containers for each protocol daemon. This cheat sheet collects the commands you actually need for day-to-day operations, from saving the running configuration to dumping Config-DB keys and troubleshooting inside containers, so you stop hunting through manuals every time you touch a SONiC switch.

What follows is deliberately built around combinations: which show, config and docker commands to chain together for a given symptom, and how to read the output of each step so you know whether to continue or stop and fix something.

How the Three Command Families Fit Together

Every SONiC task moves through the same three layers, and knowing which layer you are looking at tells you what a command can prove.

• show — reads the current state of the switch: kernel interfaces, ASIC counters, FRR routing tables, Config-DB contents. It never changes anything. Use it first, always.
• config — writes intent into Config-DB. It does not directly program the ASIC; it updates Redis and SONiC's orchestration agents then push the change into the data plane.
• docker exec — reaches into the container that owns a feature. This is where you go when the intent is right but the behaviour is wrong, because it exposes the daemon's own logs and its own view of the world.

The practical rule: verify with show, change with config, and when the two disagree, investigate with docker exec. Almost every confusing SONiC problem is a mismatch between what Config-DB says and what a container actually did with it.

Entering the SONiC CLI and Configuration Modes

admin@sonic:~$ sonic-cli
switch# configure terminal
switch(config)# interface Ethernet0
switch(config-if)#
switch(config)# exit

Configuration mode gives you access to interface, VLAN, port-channel and other configuration statements. On many builds the recommended path for configuration changes is the Linux-side config tool, which supports tab completion and --help. Note that the two shells are not interchangeable: sonic-cli is a translated front end over the same Config-DB, so a change made in one is visible in the other, but a change made in one is not guaranteed to be expressible in the other.

sonic-cli -c "show version"
sudo config --help

Show Commands (Operational State)

The CLI show commands provide a quick view of the operational state of the switch:

show interfaces status
show interfaces counters
show vlan brief
show mac
show arp
show ip route
show ip bgp summary
show lldp neighbors
show runningconfiguration

For BGP and routing-protocol details, drop into the routing container with vtysh:

docker exec -it bgp vtysh
# inside vtysh:
show bgp summary
show ip route
exit

Do not assume that show ip route run in the host shell and show ip route run inside the bgp container return the same thing. The host view reflects what the kernel believes, which includes management routes and any static routes; the FRR view reflects only the routing protocol's database. When a prefix is missing from the data plane, comparing the two is the single most informative check available.

Reading the Output: What Each Field Tells You

• show interfaces status — columns for admin state, oper state, speed and VLAN. A port that is administratively up but operationally down means the physical layer (optics, cable, FEC) is the problem, not the configuration.
• show interfaces counters rates — per-second bit and packet rates. Useful for capacity questions and to confirm a suspected one-way traffic problem: if RX is near zero while TX is high, look for a routing asymmetry rather than a cable fault.
• show interfaces counters errors — CRC, RX_ERR and RX_DROP. Non-zero CRC with a healthy link almost always means an optics or FEC mismatch between the two ends.
• show vlan brief — the authoritative list of VLANs and their member ports. If a port you configured is missing here, the configuration never reached the VLAN manager.
• show mac — the MAC learning table with VLAN, interface and type. Entries marked Dynamic prove that traffic actually arrived; an empty table on an up port means nothing has been received.
• show ip bgp summary — State/PfxRcd column. A number means the session is established and that many prefixes were received; Active, Idle or Connect mean the session is not up.

Configuration Persistence and Config-DB

All configuration is stored in a Redis database and rendered to the running system by multiple containers. Always save changes through the supported tooling:

sudo config save -y

This writes the configuration to /etc/sonic/config_db.json. To view or edit Config-DB contents directly, use the sonic-db helpers:

sonic-db-dump -y -n CONFIG_DB -k 'VLAN|Vlan100'
sonic-db-cli CONFIG_DB hgetall 'VLAN|Vlan100'

Globbing is supported with the -k key parameter; removing -k dumps the whole running configuration. Direct writes should be reserved for debugging, since the recommended abstraction is the config tool.

The combination worth memorising is the one that distinguishes the three possible states of a change:

sudo config save -y                       # running ConfigDB -> config_db.json
sudo config load /etc/sonic/config_db.json  # file -> ConfigDB (merge)
sudo config reload -y                     # file -> ConfigDB + restart services
grep -c Vlan100 /etc/sonic/config_db.json # is it in the startup file?
sonic-db-cli CONFIG_DB keys 'VLAN|*'      # is it in the running DB?

If the key appears in neither, your change was lost. If it appears in Config-DB but not in the file, you forgot to save. If it appears in the file but the feature still does not work after reload, the problem is downstream in a container and docker exec is your next step.

Common Config Commands

sudo config vlan add 100
sudo config interface ip add Ethernet0 10.0.0.1/24
sudo config portchannel add Po1
sudo config load /etc/sonic/config_db.json
sudo config reload

Two habits make these commands far safer in production. First, always follow a change with a read of the corresponding Config-DB table, so you know exactly what was written. Second, never rely on config reload to validate a change — it restarts every service and can drop traffic for tens of seconds on a busy switch.

sudo config vlan add 200
sonic-db-cli CONFIG_DB hgetall 'VLAN|Vlan200'
show vlan brief

Working Inside the Container Architecture

Each functional area (BGP, LLDP, SNMP, gNMI and so on) runs as a separate Docker container that mounts host directories and talks to the shared Redis database. Standard Docker commands work for inspection:

docker ps
docker exec -it bgp bash
docker inspect gnmi

If you need to know which files or Config-DB keys control a daemon, inspect the container's supervisor configuration and startup scripts.

docker exec -it bgp supervisorctl status
docker exec -it bgp cat /etc/supervisor/conf.d/frr.conf
docker logs syncd --tail 100
docker exec -it teamd teamdctl PortChannel0001 state

Pair the container view with the host view to localise a fault quickly:

• PortChannel stuck in individual — show interfaces portchannel on the host plus docker exec teamd teamdctl <port> state shows whether LACP itself is negotiating.
• BGP session flapping — show ip bgp summary on the host plus docker exec -it bgp vtysh -c "show bgp neighbor X" gives the last reset reason.
• Traffic not being forwarded after a config change — check docker logs syncd for SAI errors; a silent ASIC programming failure looks exactly like a routing problem from the outside.
• Counters not incrementing — docker ps | grep -i counter; if the counter container is unhealthy, the numbers you are reading are stale.

Management VRF Operations

Management traffic is isolated in the mgmt VRF on many SONiC images. Prepend commands that must reach the out-of-band network with ip vrf exec mgmt:

sudo ip vrf exec mgmt ping 8.8.8.8
sudo ip vrf exec mgmt apt update

The same pattern applies to any tool you run from the host shell: curl, ntpdate, scp, or a telemetry collector test. A command that fails with "network unreachable" on a switch that clearly has a management IP is almost always missing the VRF prefix rather than an actual network fault.

show mgmt-vrf
ip vrf show
sudo ip vrf exec mgmt curl -sI https://example.com

Log and Tech-Support Gathering

show log
sudo generate_dump

show log reads the syslog buffer and is the right first stop for anything that just broke. sudo generate_dump produces a compressed archive containing logs, Config-DB state, command output and system information, which is what a vendor support engineer will ask for. Gather it before rebooting a problem switch, because a reboot destroys the evidence.

show log | tail -100
sudo generate_dump -u          # dump without core files, smaller archive
ls -lh /var/dump/

A Repeatable Troubleshooting Sequence

When something is broken and you do not yet know what, run this chain in order and stop at the first line that looks wrong:

show interfaces status
show interfaces counters errors
show vlan brief
show mac
show ip route
show ip bgp summary
sonic-db-cli CONFIG_DB keys 'DEVICE_METADATA|*'
docker ps
show log | tail -50

This sequence moves from physical to logical to configuration to daemon, which is the order in which faults are actually distributed in practice. Skipping ahead to BGP because "the network is down" wastes the most time, since a down BGP session is usually a symptom of something several layers below it.

Worked Example: Adding a VLAN End to End

Strings of commands only become useful once you can follow one change from intent to ASIC. Suppose you need to add VLAN 300 on a leaf, trunk it to a compute host and route it. The sequence, with the question each step answers, is:

sudo config vlan add 300
sudo config vlan member add 300 Ethernet12
sudo config interface ip add Vlan300 10.30.0.1/24
sonic-db-cli CONFIG_DB keys 'VLAN|*'
show vlan brief
show ip interfaces
ping -c 3 10.30.0.2

Step one writes intent into Config-DB; the sonic-db-cli call proves the key exists with the expected attributes, which is the difference between "the command printed no error" and "the configuration was actually stored". Step two makes the configuration real in the VLAN manager and is where a typo in the port name shows up. Step three creates the SVI and gives you the routed interface. Step four proves the host is reachable.

Now the same change inside a container, which is what you do when step four fails:

docker exec -it vlanmgrd supervisorctl status
docker exec -it swss bash -c "redis-cli -n 6 keys 'VLAN*'"
docker exec -it bgp vtysh -c "show ip route 10.30.0.0/24"
docker logs syncd --tail 30

If the key exists in Config-DB but not in the ASIC-facing database, the vlanmgrd or syncd container is the fault domain — restart it and watch the logs, rather than re-running the config command. If the key reaches the ASIC database but the SVI never appears in show ip interfaces, the problem is in the interface manager and the fix is almost always a missing or misspelled port name. This three-layer walk — intent, database, data plane — is the single most valuable habit to build on SONiC, and it applies identically to VLANs, port channels, ACLs and VRFs.

Related reading: SONiC CLI Commands: show, config and sonic-cli Modes, SONiC config_db.json: Save, Reload and Replace Safely and SONiC CLI Cheat Sheet: Management VRF and Database Commands.

Original article: https://wikitech.wikimedia.org/wiki/SONiC/cheatsheet | sonic-utilities Command Reference (GitHub)