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 awk and cut read, 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 client and show wlan join what the device splits
🎨 Pretty output: --pretty borders 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 (deauth unavailable)
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:

Cisco IOS XE 17.15 Programmability Configuration Guide — RESTCONF

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_arm64 and windows_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 --help names 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

--insecure disables 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.