README
¶
wnc
A command-line interface for Cisco Catalyst 9800 Wireless Network Controllers.
Overview
This CLI reads Catalyst 9800 controllers over RESTCONF and prints their state as a table or JSON.
- 📤 Shell-friendly: A borderless table
awkandcutread, and a JSON array keyed by the sort names - 🌐 Multi-controller: Read concurrently, each row labelled with its own, and a partial read prints
- 🔭 Joined views:
show overview,show ap,show clientandshow wlanjoin what the device splits - 🎨 Pretty output:
--prettyborders the table and glyphs the state columns, never the JSON
Supported Environment
Cisco Catalyst 9800 Wireless Network Controller running on:
- Cisco IOS-XE 17.12.x — Verified on 17.12.8 (
deauthunavailable) - Cisco IOS-XE 17.15.x — Verified on 17.15.6
- Cisco IOS-XE 17.18.x — Verified on 17.18.4a
Quick Start
Please enable RESTCONF and HTTPS on the Catalyst 9800 before using this CLI. Please see:
1. Install the CLI
docker run --rm ghcr.io/umatare5/wnc:latest --help
[!TIP] If you prefer using binaries, download them from the Release.
Supported Platform:
linux_amd64,linux_arm64,darwin_amd64,darwin_arm64andwindows_amd64
2. Generate a Basic Auth token
Encode your controller account as Base64.
read -rs WNC_PASSWORD && export WNC_PASSWORD
export WNC_ACCESS_TOKEN="$(wnc generate-token -u admin)"
3. Set required environment variables
export WNC_CONTROLLER="wnc1.example.internal"
--controller is repeatable, so several controllers need no separator at all:
wnc show overview -c wnc1.example.internal -c wnc2.example.internal
4. Read the controller
wnc show overview
[!TIP]
wnc completion <shell>writes the script to stdout, and--helpnames each shell and the line it needs.
Syntax
wnc --help prints every flag, and docs/README.md indexes the reference pages behind it.
The show commands read a controller and print:
| Command | What it does |
|---|---|
wnc show overview |
One row per radio, with the RF settings and the load on it |
wnc show ap |
One row per access point |
wnc show ap-join |
One row per access point the controller remembers, joined or not |
wnc show ap-tag |
One row per access point, with the tags in force on it |
wnc show client |
One row per associated client |
wnc show wlan |
One row per WLAN and the policy profile bound to it |
wnc show policy-tag |
One row per WLAN binding a policy tag carries |
wnc show site-tag |
One row per site tag, with the profiles it names |
wnc show rf-tag |
One row per RF tag, with its profile on each band |
The commands below act on a controller, in the order they all keep:
| Command | What it does |
|---|---|
wnc reset ap |
Restart one access point |
wnc reset capwap |
Reset one access point's controller session |
wnc (enable|disable) (ap|radio) |
Set an access point's or one radio's admin state |
wnc set (policy|site|rf)-tag |
Create or update one tag |
wnc delete (policy|site|rf)-tag |
Delete one tag |
wnc deauth |
Deauthenticate a client, by address or by username |
Two commands stand outside both groups, each for a reason of its own:
| Command | What makes it different |
|---|---|
wnc generate-token |
Contacts no controller — it encodes an account and prints it |
wnc save-config |
Names no target, so it persists every change on the controller |
Configuration
Three environment variables reach every command:
| Variable | Description |
|---|---|
WNC_CONTROLLER |
Controller host[:port], comma separated for several |
WNC_ACCESS_TOKEN |
Basic auth token applied to every controller |
WNC_CONFIG |
Configuration file path, replacing the default location |
wnc generate-token reads WNC_USERNAME and WNC_PASSWORD instead, and contacts no controller. A configuration file keeps the token out of the shell history and the process arguments — see docs/configuration.md.
[!CAUTION]
--insecuredisables TLS verification. Never use it in production — trust the issuer instead.
Troubleshooting
A failed read is one stderr line ending in (cause=…), and a usage fault or a refusal is one wnc: … line. docs/troubleshooting.md indexes both, and --log-level debug restores the logfmt form.
Contributing
See CONTRIBUTING.md for the make targets, the Docker build and the release process.
Acknowledgement
I launched this project with the help of GitHub Copilot Coding Agent, and I am grateful to the global developer community for their contributions to open source projects and public repositories.
Licence
MIT. The binary statically links MIT and BSD 3-Clause dependencies, whose notices are reproduced in NOTICE and shipped alongside LICENSE 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. |