# sonic-net/sonic-utilities architecture

> Architecture diagram of the GitHub repository sonic-net/sonic-utilities, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sonic-net/sonic-utilities
- Repository: https://github.com/sonic-net/sonic-utilities

## Overview

SONiC Utilities is a collection of command-line tools for configuring, inspecting, and operating SONiC switches. The principal workflow is an operator invoking a command, which performs a domain-specific action—such as changing configuration, querying switch state, or clearing counters—and reports a result. Separate tools manage configuration patches, software images, and packages, while hardware-facing utilities expose platform and transceiver operations. Shared CLI, database, and multi-ASIC helpers support these commands. The graph follows documented capabilities and source-index references; unsampled implementations and unshown runtime wiring are not inferred.

Main entry points: [`utilities_common/cli.py`](https://github.com/sonic-net/sonic-utilities/blob/master/utilities_common/cli.py) (CLI helpers), [`utilities_common/multi_asic.py`](https://github.com/sonic-net/sonic-utilities/blob/master/utilities_common/multi_asic.py) (Multi-ASIC support), [`show/main.py`](https://github.com/sonic-net/sonic-utilities/blob/master/show/main.py) (Show commands), [`utilities_common/db.py`](https://github.com/sonic-net/sonic-utilities/blob/master/utilities_common/db.py) (Database helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli_domains["Switch CLI"]
  node_show_cli["Show commands<br/>[main.py]"]
  node_show_domains["Domain displays"]
  node_clear_cli["Clear commands<br/>[main.py]"]
  node_counterpoll["Counter polling<br/>[main.py]"]
  node_crm["Resource monitoring<br/>[main.py]"]
  node_pfcwd["PFC watchdog<br/>[main.py]"]
end

subgraph group_config_tools["Configuration"]
  node_config_cli["Configuration commands<br/>[main.py]"]
  node_config_features["Feature configuration<br/>[feature.py]"]
  node_config_management["Config management<br/>[config_mgmt.py]"]
  node_gcu_cli["Patch updater<br/>[main.py]"]
  node_gcu_engine["Patch engine<br/>[generic_updater.py]"]
end

subgraph group_software_lifecycle["Software Lifecycle"]
  node_installer["Image installer<br/>[main.py]"]
  node_package_manager["Package manager<br/>[manager.py]"]
  node_package_database[("Package database<br/>[database.py]")]
end

subgraph group_hardware_tools["Hardware Utilities"]
  node_sfp_utility["Transceiver utility<br/>[main.py]"]
  node_platform_utilities["Platform utilities<br/>[main.py]"]
end

subgraph group_shared_runtime["Shared Runtime"]
  node_cli_helpers["CLI helpers<br/>[cli.py]"]
  node_db_helpers[("Database helpers<br/>[db.py]")]
  node_multi_asic["Multi-ASIC support<br/>[multi_asic.py]"]
  node_plugin_loader["Plugin loader<br/>[util_base.py]"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_show_cli
node_operator -->|"runs commands"| node_config_cli
node_operator -->|"runs commands"| node_clear_cli
node_operator -->|"runs commands"| node_sfp_utility
node_show_cli -->|"imports displays"| node_show_domains
node_show_cli -->|"uses database"| node_db_helpers
node_show_cli -->|"uses CLI helpers"| node_cli_helpers
node_clear_cli -->|"uses CLI helpers"| node_cli_helpers
node_clear_cli -->|"uses ASIC support"| node_multi_asic
node_counterpoll -->|"uses ASIC support"| node_multi_asic
node_crm -->|"uses ASIC support"| node_multi_asic
node_crm -->|"imports displays"| node_cli_helpers
node_pfcwd -->|"uses ASIC support"| node_multi_asic
node_config_cli -->|"imports patch engine"| node_gcu_engine
node_config_cli -->|"imports updater"| node_gcu_cli
node_config_cli -->|"uses database"| node_db_helpers
node_config_features -->|"uses CLI helpers"| node_cli_helpers
node_config_features -->|"uses database connector"| node_db_helpers
node_config_management -->|"uses CLI helpers"| node_cli_helpers
node_gcu_cli -->|"calls patch logic"| node_gcu_engine
node_gcu_engine -.->|"imports shared utilities"| node_cli_helpers
node_installer -->|"uses CLI helpers"| node_cli_helpers
node_package_manager -->|"uses database"| node_package_database
node_package_database -.->|"imports shared utilities"| node_cli_helpers
node_sfp_utility -->|"uses shared utilities"| node_cli_helpers
node_sfp_utility -->|"uses platform helpers"| node_platform_utilities
node_db_helpers -->|"uses ASIC support"| node_multi_asic
node_cli_helpers -->|"uses database"| node_db_helpers
node_cli_helpers -.->|"uses ASIC support"| node_multi_asic
node_plugin_loader -.->|"registers plugins"| node_show_cli

click node_show_cli "https://github.com/sonic-net/sonic-utilities/blob/master/show/main.py"
click node_show_domains "https://github.com/sonic-net/sonic-utilities/tree/master/show"
click node_clear_cli "https://github.com/sonic-net/sonic-utilities/blob/master/clear/main.py"
click node_counterpoll "https://github.com/sonic-net/sonic-utilities/blob/master/counterpoll/main.py"
click node_crm "https://github.com/sonic-net/sonic-utilities/blob/master/crm/main.py"
click node_pfcwd "https://github.com/sonic-net/sonic-utilities/blob/master/pfcwd/main.py"
click node_config_cli "https://github.com/sonic-net/sonic-utilities/blob/master/config/main.py"
click node_config_features "https://github.com/sonic-net/sonic-utilities/blob/master/config/feature.py"
click node_config_management "https://github.com/sonic-net/sonic-utilities/blob/master/config/config_mgmt.py"
click node_gcu_cli "https://github.com/sonic-net/sonic-utilities/blob/master/generic_config_updater/main.py"
click node_gcu_engine "https://github.com/sonic-net/sonic-utilities/blob/master/generic_config_updater/generic_updater.py"
click node_installer "https://github.com/sonic-net/sonic-utilities/blob/master/sonic_installer/main.py"
click node_package_manager "https://github.com/sonic-net/sonic-utilities/blob/master/sonic_package_manager/manager.py"
click node_package_database "https://github.com/sonic-net/sonic-utilities/blob/master/sonic_package_manager/database.py"
click node_sfp_utility "https://github.com/sonic-net/sonic-utilities/blob/master/sfputil/main.py"
click node_platform_utilities "https://github.com/sonic-net/sonic-utilities/blob/master/pddf_fanutil/main.py"
click node_cli_helpers "https://github.com/sonic-net/sonic-utilities/blob/master/utilities_common/cli.py"
click node_db_helpers "https://github.com/sonic-net/sonic-utilities/blob/master/utilities_common/db.py"
click node_multi_asic "https://github.com/sonic-net/sonic-utilities/blob/master/utilities_common/multi_asic.py"
click node_plugin_loader "https://github.com/sonic-net/sonic-utilities/blob/master/utilities_common/util_base.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_show_cli,node_show_domains,node_clear_cli,node_counterpoll,node_crm,node_pfcwd toneBlue
class node_config_cli,node_config_features,node_config_management,node_gcu_cli,node_gcu_engine toneAmber
class node_installer,node_package_manager,node_package_database toneMint
class node_sfp_utility,node_platform_utilities toneRose
class node_cli_helpers,node_db_helpers,node_multi_asic,node_plugin_loader,node_operator toneIndigo
```

## Components

### Switch CLI

- [Show commands](https://github.com/sonic-net/sonic-utilities/blob/master/show/main.py): `show/main.py`
- [Domain displays](https://github.com/sonic-net/sonic-utilities/tree/master/show): `show`
- [Clear commands](https://github.com/sonic-net/sonic-utilities/blob/master/clear/main.py): `clear/main.py`
- [Counter polling](https://github.com/sonic-net/sonic-utilities/blob/master/counterpoll/main.py): `counterpoll/main.py`
- [Resource monitoring](https://github.com/sonic-net/sonic-utilities/blob/master/crm/main.py): `crm/main.py`
- [PFC watchdog](https://github.com/sonic-net/sonic-utilities/blob/master/pfcwd/main.py): `pfcwd/main.py`

### Configuration

- [Configuration commands](https://github.com/sonic-net/sonic-utilities/blob/master/config/main.py): `config/main.py`
- [Feature configuration](https://github.com/sonic-net/sonic-utilities/blob/master/config/feature.py): `config/feature.py`
- [Config management](https://github.com/sonic-net/sonic-utilities/blob/master/config/config_mgmt.py): `config/config_mgmt.py`
- [Patch updater](https://github.com/sonic-net/sonic-utilities/blob/master/generic_config_updater/main.py): `generic_config_updater/main.py`
- [Patch engine](https://github.com/sonic-net/sonic-utilities/blob/master/generic_config_updater/generic_updater.py): `generic_config_updater/generic_updater.py`

### Software Lifecycle

- [Image installer](https://github.com/sonic-net/sonic-utilities/blob/master/sonic_installer/main.py): `sonic_installer/main.py`
- [Package manager](https://github.com/sonic-net/sonic-utilities/blob/master/sonic_package_manager/manager.py): `sonic_package_manager/manager.py`
- [Package database](https://github.com/sonic-net/sonic-utilities/blob/master/sonic_package_manager/database.py): `sonic_package_manager/database.py`

### Hardware Utilities

- [Transceiver utility](https://github.com/sonic-net/sonic-utilities/blob/master/sfputil/main.py): `sfputil/main.py`
- [Platform utilities](https://github.com/sonic-net/sonic-utilities/blob/master/pddf_fanutil/main.py): `pddf_fanutil/main.py`

### Shared Runtime

- [CLI helpers](https://github.com/sonic-net/sonic-utilities/blob/master/utilities_common/cli.py): `utilities_common/cli.py`
- [Database helpers](https://github.com/sonic-net/sonic-utilities/blob/master/utilities_common/db.py): `utilities_common/db.py`
- [Multi-ASIC support](https://github.com/sonic-net/sonic-utilities/blob/master/utilities_common/multi_asic.py): `utilities_common/multi_asic.py`
- [Plugin loader](https://github.com/sonic-net/sonic-utilities/blob/master/utilities_common/util_base.py): `utilities_common/util_base.py`

### Other components

- **Operator**

## Connections

- Operator → Show commands: runs commands
- Operator → Configuration commands: runs commands
- Operator → Clear commands: runs commands
- Operator → Transceiver utility: runs commands
- Show commands → Domain displays: imports displays (evidence: `show/main.py`)
- Show commands → Database helpers: uses database (evidence: `show/main.py`)
- Show commands → CLI helpers: uses CLI helpers (evidence: `show/main.py`)
- Clear commands → CLI helpers: uses CLI helpers (evidence: `clear/main.py`)
- Clear commands → Multi-ASIC support: uses ASIC support (evidence: `clear/main.py`)
- Counter polling → Multi-ASIC support: uses ASIC support (evidence: `counterpoll/main.py`)
- Resource monitoring → Multi-ASIC support: uses ASIC support (evidence: `crm/main.py`)
- Resource monitoring → CLI helpers: imports displays (evidence: `crm/main.py`)
- PFC watchdog → Multi-ASIC support: uses ASIC support (evidence: `pfcwd/main.py`)
- Configuration commands → Patch engine: imports patch engine (evidence: `config/main.py`)
- Configuration commands → Patch updater: imports updater (evidence: `config/main.py`)
- Configuration commands → Database helpers: uses database (evidence: `config/main.py`)
- Feature configuration → CLI helpers: uses CLI helpers (evidence: `config/feature.py`)
- Feature configuration → Database helpers: uses database connector (evidence: `config/feature.py`)
- Config management → CLI helpers: uses CLI helpers (evidence: `config/config_mgmt.py`)
- Patch updater → Patch engine: calls patch logic (evidence: `generic_config_updater/main.py`)
- Patch engine → CLI helpers: imports shared utilities
- Image installer → CLI helpers: uses CLI helpers (evidence: `sonic_installer/main.py`)
- Package manager → Package database: uses database (evidence: `sonic_package_manager/manager.py`)
- Package database → CLI helpers: imports shared utilities
- Transceiver utility → CLI helpers: uses shared utilities (evidence: `sfputil/main.py`)
- Transceiver utility → Platform utilities: uses platform helpers (evidence: `sfputil/main.py`)
- Database helpers → Multi-ASIC support: uses ASIC support (evidence: `utilities_common/db.py`)
- CLI helpers → Database helpers: uses database (evidence: `utilities_common/cli.py`)
- CLI helpers → Multi-ASIC support: uses ASIC support
- Plugin loader → Show commands: registers plugins (evidence: `show/main.py`)