8.0 KiB
UnifiCLI — Testing Guide
Sideloading the Module
Prerequisites
Confirm PowerShell 7+ is installed (required — Windows PowerShell 5.x is not supported):
$PSVersionTable.PSVersion
# Major should be 7 or higher
If you need to install it: https://aka.ms/powershell
Option A — Import for the current session only
Use this while developing or sharing with colleagues who just want to try it out. No files are copied anywhere; the module is gone when the PS window closes.
# Clone or copy the repo, then from the repo root:
Import-Module .\UnifiCLI.psd1 -Force
# Confirm it loaded
Get-Module UnifiCLI
Option B — Install to your user module path (persists across sessions)
This makes Import-Module UnifiCLI work from any directory, any window.
# Find your user module directory
$env:PSModulePath -split ';'
# Pick the one under your profile, e.g. C:\Users\<you>\Documents\PowerShell\Modules
# Copy the whole repo folder there
$dest = "$HOME\Documents\PowerShell\Modules\UnifiCLI"
Copy-Item -Path 'C:\path\to\UnifiCLI' -Destination $dest -Recurse -Force
# Now load it from anywhere
Import-Module UnifiCLI -Force
To uninstall:
Remove-Item "$HOME\Documents\PowerShell\Modules\UnifiCLI" -Recurse -Force
Verify the module loaded correctly
Get-Command -Module UnifiCLI
# Should list: Connect-UnifiController, Disconnect-UnifiController,
# Get-UnifiConnectionStatus, Get-UnifiSite, Get-UnifiDevice,
# Get-UnifiClient, Get-UnifiWlan, Set-UnifiWlanPassword, Invoke-UnifiCli
Get-Alias unifi-cli
# Should resolve to Invoke-UnifiCli
Phase 1 — Connect / Disconnect / Status
1.1 Help output (no arguments)
unifi-cli
Expected: Usage block listing all available commands. No errors.
1.2 Status when not connected
unifi-cli status
# or
Get-UnifiConnectionStatus
Expected: Red "Not connected" message with a hint to run connect.
1.3 Connect — credential prompt
unifi-cli connect 192.168.1.1 --insecure
Expected: A credential prompt appears. After entering valid admin credentials, output shows:
Connected to https://192.168.1.1:443 as <username>
1.4 Connect — inline credential (useful for scripting, not recommended for shared sessions)
$cred = Get-Credential
Connect-UnifiController -Controller 192.168.1.1 -Credential $cred -SkipCertificateCheck
Expected: Same green "Connected" output without a second prompt.
1.5 Connect with non-default port
unifi-cli connect 192.168.1.1 --port 8443 --insecure
Expected: Connects to https://192.168.1.1:8443. URL shown in status reflects the port.
1.6 Status when connected
unifi-cli status
Expected: All fields populated — Controller, Username, Connected timestamp, Site (default).
If --insecure was used, a yellow TLS warning line should appear.
1.7 Connect with --save
unifi-cli connect 192.168.1.1 --insecure --save
Expected: Connects successfully. Verify the config file was written (password must NOT appear):
Get-Content "$env:APPDATA\UnifiCLI\config.json"
# Should show ControllerUrl, Username, SkipCertificateCheck — no password field
1.8 Disconnect
unifi-cli disconnect
Expected: Yellow "Disconnected." message.
1.9 Status after disconnect
unifi-cli status
Expected: Back to red "Not connected" state.
1.10 Disconnect when not connected
unifi-cli disconnect
Expected: Warning saying "Not currently connected to a controller." — no crash.
1.11 Wrong password
Connect-UnifiController -Controller 192.168.1.1 -SkipCertificateCheck `
-Credential (New-Object PSCredential('admin', (ConvertTo-SecureString 'wrongpassword' -AsPlainText -Force)))
Expected: Error message from the controller (e.g. "Login rejected by controller: Invalid credentials").
Session must NOT be set — verify with unifi-cli status showing "Not connected".
1.12 Unreachable host
unifi-cli connect 10.255.255.1 --insecure
Expected: Connection error (timeout or refused). No crash, no partial session state.
Verify unifi-cli status still shows "Not connected".
1.13 Phase 2 stub — should not crash
# Connect first (1.3 or 1.4), then:
unifi-cli list sites
Expected: Yellow warning: "Get-UnifiSite is not yet implemented (Phase 2)." — no error.
1.14 Phase 2 stub — not connected
# Without connecting first:
unifi-cli list sites
Expected: Error: "Not connected. Run Connect-UnifiController first."
Phase 2 — Read Commands (complete once Phase 2 is built)
2.1 List all sites
unifi-cli list sites
# or
Get-UnifiSite
Expected: Table or list of sites with at minimum Site ID and Description columns.
Multi-site controllers should show multiple rows. Single-site will show just default.
2.2 List devices
unifi-cli list devices
# or
Get-UnifiDevice -Site default
Expected: List of adopted Unifi devices (APs, switches, gateways) with name, model, MAC, and state.
2.3 List active clients
unifi-cli list clients
# or
Get-UnifiClient -Site default -Active
Expected: List of currently connected clients with hostname, IP, MAC, SSID or port.
2.4 List WLANs
unifi-cli list wlans
# or
Get-UnifiWlan -Site default
Expected: Table of SSIDs with name, enabled state, security mode. Passwords should NOT appear in default output.
2.5 Filter WLAN by SSID name
Get-UnifiWlan -Site default -Ssid 'georgiou-guest'
Expected: Returns only the matching SSID entry.
2.6 Non-default site
Get-UnifiDevice -Site <site-id-from-2.1>
Expected: Devices scoped to that site, not all sites combined.
Phase 3 — Write Commands (complete once Phase 3 is built)
3.1 Rotate password — single site, prompt
Set-UnifiWlanPassword -Ssid 'georgiou-guest' -Site default
Expected: Secure password prompt appears. After entry, success message.
Verify by running Get-UnifiWlan -Ssid 'georgiou-guest' and confirming the new password.
3.2 Rotate password — inline SecureString
$newPass = ConvertTo-SecureString 'NewP@ss99' -AsPlainText -Force
Set-UnifiWlanPassword -Ssid 'georgiou-guest' -Site default -NewPassword $newPass
Expected: Password updated without prompting.
3.3 WhatIf — no change should be made
Set-UnifiWlanPassword -Ssid 'georgiou-guest' -Site default -WhatIf
Expected: Output describes what would happen. No API call is made. Password unchanged.
3.4 Rotate across all sites
Get-UnifiSite | ForEach-Object {
Set-UnifiWlanPassword -Ssid 'georgiou-guest' -Site $_.Name -NewPassword $newPass
}
Expected: Each site processed in sequence. Sites without the target SSID report "not found" rather than erroring.
3.5 SSID not found on site
Set-UnifiWlanPassword -Ssid 'ssid-that-does-not-exist' -Site default
Expected: Clear message that the SSID was not found. No error thrown, no partial update.
Regression Checks (run after any phase)
| Check | Command | Pass condition |
|---|---|---|
| Module loads | Import-Module .\UnifiCLI.psd1 -Force |
No errors |
| All commands present | Get-Command -Module UnifiCLI |
9 functions listed |
| Alias works | Get-Alias unifi-cli |
Resolves to Invoke-UnifiCli |
| Help renders | unifi-cli |
Usage block with no errors |
| Status clean | unifi-cli status (not connected) |
"Not connected" — no exceptions |
| Config has no password | Get-Content "$env:APPDATA\UnifiCLI\config.json" |
No password key present |