README
¶
cisco-wnc-cli
A command-line interface for Cisco Catalyst 9800 Wireless Network Controllers.
Overview
This CLI manages wireless LANs across multiple Cisco Catalyst 9800 Wireless Network Controllers.
- 🌐 Unified Views: Reads multiple WLCs at once, so load-balanced APs share one table
- 🔭 Joined Rows: Combines several RESTCONF models into one row per radio, AP or client
- 💻️ Shell Friendly: Provides borderless tables for
grep,awk,sedandcut, and JSON forjq - 🎨 Flexible Output: Supports
--prettyfor humans, and--format jsonfor machines and AIs
Supported Environment
Cisco Catalyst 9800 Wireless Network Controller running on:
- Cisco IOS-XE 17.12.5 or later – Last verified on 17.12.8, with no
wnc deauthbefore 17.15.6 - Cisco IOS-XE 17.15.6 or later – Last verified on 17.15.6
- Cisco IOS-XE 17.18.4a or later – Last verified on 17.18.4a
[!IMPORTANT] This CLI requires these minimum versions due to RESTCONF defects in earlier releases. It fails on 17.15.4b and 17.18.1. See cisco-ios-xe-wireless-go #28 and cisco-ios-xe-wireless-go #29 for details.
Installation
This CLI supports container images and OS-specific binaries.
docker pull ghcr.io/umatare5/wnc
Or, download the binaries from Releases.
(linux|darwin)_(amd64|arm64) and windows_amd64 are supported.
Quick Start
This CLI requires RESTCONF and HTTPS to be enabled on the Cisco Catalyst 9800 beforehand.
See the Programmability Configuration Guide, Cisco IOS XE 17.15.x – RESTCONF for enabling them.
1. Generate a Basic Auth token
read -rs WNC_PASSWORD # < your-password
printf '%s' "$WNC_PASSWORD" | wnc generate-token -u admin
# Output: YWRtaW46eW91ci1wYXNzd29yZA== (admin:your-password)
2. Set the environment variables
export WNC_CONTROLLER="wnc1.example.internal"
export WNC_ACCESS_TOKEN="YWRtaW46eW91ci1wYXNzd29yZA=="
3. Print a wireless overview
wnc show overview
[!TIP]
wnc completion <shell>writes the script to stdout, and--helpnames each shell and the line it needs.
CLI Reference
This CLI groups commands by purpose. Each links to a section showing its output.
Show commands
These commands read a controller and print a table or JSON. See Show commands for details.
| Command | Description |
|---|---|
wnc show overview |
One row per radio, with RF summary across 2.4, 5 and 6 GHz |
wnc show ap |
One row per associated access point |
wnc show ap-join |
One row per access point's join, discovery and DTLS outcome |
wnc show ap-tag |
One row per access point, with assigned and resolved tags |
wnc show client |
One row per associated wireless client |
wnc show wlan |
One row per WLAN and its bound policy profile |
wnc show policy-tag |
One row per policy tag and the WLANs it binds |
wnc show site-tag |
One row per site tag and the profiles it names |
wnc show rf-tag |
One row per RF tag and its per-band RF profiles |
Action commands
These commands act on a controller in order. See Action commands for details.
| Command | Description |
|---|---|
wnc reset ap |
Restart one access point |
wnc reset capwap |
Reset one access point's controller session |
wnc (enable|disable) (ap|radio) |
Enable or disable one access point or one radio |
wnc set (policy|site|rf)-tag |
Create or update one tag on a controller |
wnc delete (policy|site|rf)-tag |
Delete one tag from a controller |
wnc deauth |
Deauthenticate one client by MAC or username |
Other commands
These commands stand outside both groups for specific reasons. See Other commands for details.
| Command | Description |
|---|---|
wnc generate-token |
Generate the Basic auth token for a controller account |
wnc save-config |
Save the running configuration to the startup configuration |
Help
--help lists commands and flags. See Help for all transcripts except completion.
Customization
This CLI reads its settings from flags, environment variables and a config file. See Customization for the details.
Documentation
Both pages below are written for a contributor rather than an operator.
- Architecture – the output contract, the absence rule, the exit codes, and the write order
- Measurements – every reading taken on a live controller, and the gaps
- Troubleshooting – every error message this CLI prints, and what each one means
Contributing
See CONTRIBUTING.md for the development setup, the test conventions and the release steps.
License
MIT. The binary statically links MIT and BSD 3-Clause dependencies, so their notices are reproduced in NOTICE.
LICENSE ships beside it in every release archive and container image.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package main is the wnc entry point.
|
Package main is the wnc entry point. |
|
internal
|
|
|
cli
Package cli wires the command tree, owns the process exit code, and is the only place that decides what reaches stdout and what reaches stderr.
|
Package cli wires the command tree, owns the process exit code, and is the only place that decides what reaches stdout and what reaches stderr. |
|
config
Package config resolves one run's settings from the flags, the environment and an optional JSON file, in that order of precedence.
|
Package config resolves one run's settings from the flags, the environment and an optional JSON file, in that order of precedence. |
|
log
Package log builds the process logger and the slog bridge the WNC SDK takes.
|
Package log builds the process logger and the slog bridge the WNC SDK takes. |
|
render
Package render turns a slice of rows into a borderless table, a bordered one, or a flat JSON array.
|
Package render turns a slice of rows into a borderless table, a bordered one, or a flat JSON array. |
|
show
Package show fans one read out across the configured controllers, joins what each answered into rows, and hands them to a renderer.
|
Package show fans one read out across the configured controllers, joins what each answered into rows, and hands them to a renderer. |
|
wnc
Package wnc is the only place that imports the RESTCONF SDK.
|
Package wnc is the only place that imports the RESTCONF SDK. |