unifi-cli 0.2.3__tar.gz → 0.3.0__tar.gz

{unifi_cli-0.2.3 → unifi_cli-0.3.0}/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 
 
 
+
+## [0.3.0](https://github.com/rvben/unifi-cli/compare/v0.2.3...v0.3.0) - 2026-07-09
+
+### Fixed
+
+- **clients**: stop three silent-failure modes in the agent contract ([5e50bb7](https://github.com/rvben/unifi-cli/commit/5e50bb704777407acf244856bc435f7ceccd7b00))
+
 ## [0.2.3](https://github.com/rvben/unifi-cli/compare/v0.2.2...v0.2.3) - 2026-07-07
 
 ### Fixed

{unifi_cli-0.2.3 → unifi_cli-0.3.0}/Cargo.lock

@@ -2786,7 +2786,7 @@ checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
 
 [[package]]
 name = "unifi-cli"
-version = "0.2.3"
+version = "0.3.0"
 dependencies = [
  "clap",
  "clap_complete",

{unifi_cli-0.2.3 → unifi_cli-0.3.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "unifi-cli"
-version = "0.2.3"
+version = "0.3.0"
 edition = "2024"
 rust-version = "1.90"
 description = "CLI for UniFi Network controller"

{unifi_cli-0.2.3 → unifi_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unifi-cli
-Version: 0.2.3
+Version: 0.3.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: System Administrators
@@ -151,6 +151,7 @@ unifi clients list                          # List connected clients
 unifi clients list --wired                  # Wired clients only
 unifi clients list --wireless --name tasmota  # Filter by type and name
 unifi clients list --watch                  # Auto-refresh
+unifi clients list --fields name,ssid,ip    # Project specific fields (see `unifi schema`)
 unifi clients show aa:bb:cc:dd:ee:ff        # Show client details
 unifi clients top                           # Top clients by bandwidth
 unifi clients block aa:bb:cc:dd:ee:ff       # Block a client
@@ -182,7 +183,8 @@ unifi events list --limit 50                # Last 50 events
 ### Networks
 
 ```bash
-unifi networks                              # List all networks
+unifi networks list                         # List all networks
+unifi networks                              # Same thing
 ```
 
 ### System

{unifi_cli-0.2.3 → unifi_cli-0.3.0}/README.md

@@ -130,6 +130,7 @@ unifi clients list                          # List connected clients
 unifi clients list --wired                  # Wired clients only
 unifi clients list --wireless --name tasmota  # Filter by type and name
 unifi clients list --watch                  # Auto-refresh
+unifi clients list --fields name,ssid,ip    # Project specific fields (see `unifi schema`)
 unifi clients show aa:bb:cc:dd:ee:ff        # Show client details
 unifi clients top                           # Top clients by bandwidth
 unifi clients block aa:bb:cc:dd:ee:ff       # Block a client
@@ -161,7 +162,8 @@ unifi events list --limit 50                # Last 50 events
 ### Networks
 
 ```bash
-unifi networks                              # List all networks
+unifi networks list                         # List all networks
+unifi networks                              # Same thing
 ```
 
 ### System

{unifi_cli-0.2.3 → unifi_cli-0.3.0}/src/api/types.rs

@@ -38,12 +38,19 @@ pub struct Site {
 pub struct Client {
     #[serde(alias = "macAddress")]
     pub mac_address: Option<String>,
+    /// The last address the controller recorded for this client. It outlives the
+    /// lease, so it can name an address the client no longer holds. `clients list`
+    /// reports the live address from `stat/sta` instead, so that it agrees with
+    /// `clients show`.
     #[serde(alias = "ipAddress")]
     pub ip_address: Option<String>,
     pub name: Option<String>,
     pub hostname: Option<String>,
     #[serde(alias = "type")]
     pub client_type: Option<String>,
+    /// ISO8601 timestamp of the current association.
+    #[serde(alias = "connectedAt")]
+    pub connected_at: Option<String>,
 }
 
 impl Client {
@@ -83,6 +90,10 @@ pub struct LegacyClient {
     pub ap_mac: Option<String>,
     #[serde(rename = "essid")]
     pub ssid: Option<String>,
+    /// Name of the network the client landed on ("Default", "IoT", ...). Absent
+    /// while the client is associated but has not obtained an address.
+    pub network: Option<String>,
+    pub vlan: Option<u32>,
 }
 
 impl LegacyClient {

{unifi_cli-0.2.3 → unifi_cli-0.3.0}/src/commands/clients.rs

@@ -14,7 +14,77 @@ pub struct ListFilter {
 pub struct Pagination {
     pub limit: usize,
     pub offset: usize,
-    pub fields: Option<String>,
+    /// Field names already validated against `fields::CLIENTS_LIST`.
+    pub fields: Option<Vec<String>>,
+}
+
+/// A client as `clients list` reports it: the integration-API record joined with
+/// the live legacy record for the same MAC.
+///
+/// The integration API knows every client the controller has seen and carries
+/// `connectedAt`. Only the legacy `stat/sta` record carries the live address,
+/// SSID, signal, network and VLAN. Neither alone answers "which SSID is each
+/// client on", and reading `ip` from the integration record makes `clients list`
+/// disagree with `clients show` whenever a client has lost its lease.
+pub(crate) struct ClientRow {
+    pub client: Client,
+    pub detail: Option<LegacyClient>,
+}
+
+impl ClientRow {
+    /// The address the client holds right now, or None while it has none.
+    ///
+    /// Deliberately not `Client::ip_address`, which is the last address the
+    /// controller ever saw and lingers long after the lease is gone.
+    pub fn live_ip(&self) -> Option<&str> {
+        self.detail.as_ref().and_then(|d| d.ip.as_deref())
+    }
+
+    pub fn to_json(&self) -> serde_json::Value {
+        let c = &self.client;
+        let d = self.detail.as_ref();
+        serde_json::json!({
+            "name": c.clean_name(),
+            "mac": c.mac_address.as_deref().map(|m| format_mac(&normalize_mac(m))),
+            "ip": self.live_ip(),
+            "type": c.client_type,
+            "ssid": d.and_then(|d| d.ssid.as_deref()),
+            "signal": d.and_then(|d| d.signal),
+            "uptime": d.and_then(|d| d.uptime),
+            "network": d.and_then(|d| d.network.as_deref()),
+            "vlan": d.and_then(|d| d.vlan),
+            "tx_bytes": d.and_then(|d| d.tx_bytes),
+            "rx_bytes": d.and_then(|d| d.rx_bytes),
+            "blocked": d.map(|d| d.blocked),
+            "connected_at": c.connected_at,
+        })
+    }
+}
+
+/// Join integration-API clients to their live legacy records by MAC.
+///
+/// A client with no legacy record is kept, with its live fields null. That is
+/// the honest answer: it is associated (the controller lists it) but the
+/// controller has no current address or SSID for it.
+pub(crate) fn merge_rows(clients: Vec<Client>, legacy: Vec<LegacyClient>) -> Vec<ClientRow> {
+    let mut by_mac: std::collections::HashMap<String, LegacyClient> = legacy
+        .into_iter()
+        .filter_map(|l| {
+            let key = l.mac.as_deref().map(normalize_mac)?;
+            Some((key, l))
+        })
+        .collect();
+
+    clients
+        .into_iter()
+        .map(|c| {
+            let detail = c
+                .mac_address
+                .as_deref()
+                .and_then(|m| by_mac.remove(&normalize_mac(m)));
+            ClientRow { client: c, detail }
+        })
+        .collect()
 }
 
 pub(crate) fn apply_filter(clients: Vec<Client>, filter: &ListFilter) -> Vec<Client> {
@@ -39,27 +109,15 @@ pub(crate) fn apply_filter(clients: Vec<Client>, filter: &ListFilter) -> Vec<Cli
         .collect()
 }
 
-fn render_clients(clients: &[Client], out: &OutputConfig) {
+fn render_clients(rows: &[ClientRow], out: &OutputConfig) {
     if out.is_json() {
         out.print_data(
-            &serde_json::to_string_pretty(
-                &clients
-                    .iter()
-                    .map(|c| {
-                        serde_json::json!({
-                            "name": c.clean_name(),
-                            "mac": c.mac_address.as_deref().map(|m| format_mac(&normalize_mac(m))),
-                            "ip": c.ip_address,
-                            "type": c.client_type,
-                        })
-                    })
-                    .collect::<Vec<_>>(),
-            )
-            .expect("failed to serialize JSON"),
+            &serde_json::to_string_pretty(&rows.iter().map(ClientRow::to_json).collect::<Vec<_>>())
+                .expect("failed to serialize JSON"),
         );
     } else {
         let color = use_color();
-        let names: Vec<String> = clients.iter().map(|c| c.clean_name()).collect();
+        let names: Vec<String> = rows.iter().map(|r| r.client.clean_name()).collect();
         let name_w = names.iter().map(|n| n.len()).max().unwrap_or(4).max(4) + 2;
         let total_w = name_w + 19 + 15 + 10;
         let header = format!("{:<name_w$} {:<19} {:<15} {}", "Name", "MAC", "IP", "Type");
@@ -71,14 +129,15 @@ fn render_clients(clients: &[Client], out: &OutputConfig) {
             println!("{}", "-".repeat(total_w));
         }
 
-        for (c, name) in clients.iter().zip(&names) {
-            let mac = c
+        for (r, name) in rows.iter().zip(&names) {
+            let mac = r
+                .client
                 .mac_address
                 .as_deref()
                 .map(format_mac)
                 .unwrap_or_else(|| "-".into());
-            let ip = c.ip_address.as_deref().unwrap_or("-");
-            let ctype = c.client_type.as_deref().unwrap_or("-");
+            let ip = r.live_ip().unwrap_or("-");
+            let ctype = r.client.client_type.as_deref().unwrap_or("-");
             let pad = name_w - 1;
 
             if color {
@@ -94,7 +153,7 @@ fn render_clients(clients: &[Client], out: &OutputConfig) {
             }
         }
     }
-    out.print_message(&format!("\n{} clients", clients.len()));
+    out.print_message(&format!("\n{} clients", rows.len()));
 }
 
 pub async fn list(
@@ -118,22 +177,16 @@ pub async fn list(
                 crossterm::terminal::Clear(crossterm::terminal::ClearType::All)
             )?;
             eprintln!("Every {interval}s | clients list (press Ctrl+C to exit)\n");
-            match client.list_clients().await {
-                Ok(clients) => {
-                    let filtered = apply_filter(clients, &filter);
-                    render_clients(&filtered, &out);
-                }
-                Err(e) => {
-                    eprintln!("Error: {e}");
-                }
+            match fetch_rows(client, &filter).await {
+                Ok(rows) => render_clients(&rows, &out),
+                Err(e) => eprintln!("Error: {e}"),
             }
             tokio::time::sleep(std::time::Duration::from_secs(interval)).await;
         }
     } else {
-        let clients = client.list_clients().await?;
-        let filtered = apply_filter(clients, &filter);
-        let total = filtered.len();
-        let paginated: Vec<Client> = filtered
+        let rows = fetch_rows(client, &filter).await?;
+        let total = rows.len();
+        let paginated: Vec<ClientRow> = rows
             .into_iter()
             .skip(pagination.offset)
             .take(pagination.limit)
@@ -141,21 +194,11 @@ pub async fn list(
         if out.is_json() {
             let items: Vec<serde_json::Value> = paginated
                 .iter()
-                .map(|c| {
-                    let mac_str = c
-                        .mac_address
-                        .as_deref()
-                        .map(|m| format_mac(&normalize_mac(m)));
-                    let mut obj = serde_json::json!({
-                        "name": c.clean_name(),
-                        "mac": mac_str,
-                        "ip": c.ip_address,
-                        "type": c.client_type,
-                    });
-                    if let Some(ref fields_str) = pagination.fields {
-                        let keep: Vec<&str> = fields_str.split(',').map(str::trim).collect();
-                        let map = obj.as_object_mut().unwrap();
-                        map.retain(|k, _| keep.contains(&k.as_str()));
+                .map(|r| {
+                    let mut obj = r.to_json();
+                    if let Some(ref keep) = pagination.fields {
+                        let map = obj.as_object_mut().expect("row is a JSON object");
+                        map.retain(|k, _| keep.iter().any(|f| f == k));
                     }
                     obj
                 })
@@ -176,6 +219,17 @@ pub async fn list(
     }
 }
 
+/// Fetch both client views and join them. Two calls, once, rather than one call
+/// per client for anything beyond name/mac/ip/type.
+async fn fetch_rows(
+    client: &mut UnifiClient,
+    filter: &ListFilter,
+) -> Result<Vec<ClientRow>, Box<dyn std::error::Error>> {
+    let clients = client.list_clients().await?;
+    let legacy = client.list_clients_legacy().await?;
+    Ok(merge_rows(apply_filter(clients, filter), legacy))
+}
+
 pub async fn show(
     client: &UnifiClient,
     mac: &str,
@@ -195,6 +249,9 @@ pub async fn show(
             "signal": c.signal,
             "ssid": c.ssid,
             "ap_mac": c.ap_mac,
+            "network": c.network,
+            "vlan": c.vlan,
+            "blocked": c.blocked,
         }))?);
         return Ok(());
     }
@@ -250,6 +307,15 @@ pub async fn show(
             println!("  {}  {}", label("AP:    "), format_mac(ap));
         }
     }
+    if let Some(ref network) = c.network {
+        println!("  {}  {network}", label("Network:"));
+    }
+    if let Some(vlan) = c.vlan {
+        println!("  {}  {vlan}", label("VLAN:  "));
+    }
+    if c.blocked {
+        println!("  {}  yes", label("Blocked:"));
+    }
 
     Ok(())
 }
@@ -419,6 +485,142 @@ mod tests {
         .unwrap()
     }
 
+    fn legacy(json: &str) -> LegacyClient {
+        serde_json::from_str(json).unwrap()
+    }
+
+    // --- merge_rows: `clients list` must describe a client the way `show` does ---
+
+    #[test]
+    fn merge_joins_legacy_detail_by_mac() {
+        let clients = vec![make_client(
+            "Plug",
+            "70:03:9f:90:3c:29",
+            "10.10.20.202",
+            "WIRELESS",
+        )];
+        let legacy_records = vec![legacy(
+            r#"{"_id":"1","mac":"70:03:9f:90:3c:29","ip":"10.10.20.202","essid":"Notwork",
+                "signal":-57,"uptime":321125,"network":"IoT","vlan":20}"#,
+        )];
+
+        let rows = merge_rows(clients, legacy_records);
+        assert_eq!(rows.len(), 1);
+        let json = rows[0].to_json();
+        assert_eq!(json["ssid"], "Notwork");
+        assert_eq!(json["signal"], -57);
+        assert_eq!(json["network"], "IoT");
+        assert_eq!(json["vlan"], 20);
+        assert_eq!(json["ip"], "10.10.20.202");
+    }
+
+    #[test]
+    fn merge_matches_macs_in_different_formats() {
+        let clients = vec![make_client("X", "AA-BB-CC-DD-EE-FF", "10.0.0.1", "WIRED")];
+        let legacy_records = vec![legacy(
+            r#"{"_id":"1","mac":"aa:bb:cc:dd:ee:ff","ip":"10.0.0.5"}"#,
+        )];
+        let rows = merge_rows(clients, legacy_records);
+        assert_eq!(rows[0].live_ip(), Some("10.0.0.5"));
+    }
+
+    /// The defect this guards: `clients list` read `ip` from the integration API,
+    /// which keeps the last address a client ever held. A plug that had dropped
+    /// its lease four days earlier was still reported at that address, while
+    /// `clients show` correctly reported none.
+    #[test]
+    fn live_ip_wins_over_the_integration_apis_last_known_address() {
+        let clients = vec![make_client(
+            "Refrigerator",
+            "c4:dd:57:1d:07:e6",
+            "10.10.20.203",
+            "WIRELESS",
+        )];
+        let legacy_records = vec![legacy(
+            r#"{"_id":"1","mac":"c4:dd:57:1d:07:e6","essid":"Network"}"#,
+        )];
+
+        let rows = merge_rows(clients, legacy_records);
+        assert_eq!(
+            rows[0].live_ip(),
+            None,
+            "a client with no current lease must report no ip"
+        );
+        assert_eq!(rows[0].to_json()["ip"], serde_json::Value::Null);
+        assert_eq!(rows[0].to_json()["ssid"], "Network");
+    }
+
+    #[test]
+    fn clients_without_a_legacy_record_survive_with_null_detail() {
+        let clients = vec![make_client(
+            "Ghost",
+            "aa:bb:cc:dd:ee:ff",
+            "10.0.0.1",
+            "WIRED",
+        )];
+        let rows = merge_rows(clients, vec![]);
+        assert_eq!(rows.len(), 1);
+        let json = rows[0].to_json();
+        assert_eq!(json["name"], "Ghost");
+        assert_eq!(json["ip"], serde_json::Value::Null);
+        assert_eq!(json["ssid"], serde_json::Value::Null);
+        assert_eq!(json["blocked"], serde_json::Value::Null);
+    }
+
+    #[test]
+    fn merge_preserves_client_order_and_count() {
+        let clients = vec![
+            make_client("A", "aa:bb:cc:dd:ee:01", "10.0.0.1", "WIRED"),
+            make_client("B", "aa:bb:cc:dd:ee:02", "10.0.0.2", "WIRELESS"),
+            make_client("C", "aa:bb:cc:dd:ee:03", "10.0.0.3", "WIRELESS"),
+        ];
+        let legacy_records = vec![legacy(
+            r#"{"_id":"1","mac":"aa:bb:cc:dd:ee:02","ip":"1.2.3.4"}"#,
+        )];
+        let rows = merge_rows(clients, legacy_records);
+        let names: Vec<String> = rows
+            .iter()
+            .map(|r| r.client.clean_name())
+            .collect::<Vec<_>>();
+        assert_eq!(names, vec!["A", "B", "C"]);
+        assert_eq!(rows[1].live_ip(), Some("1.2.3.4"));
+        assert_eq!(rows[0].live_ip(), None);
+    }
+
+    #[test]
+    fn merge_ignores_legacy_records_with_no_matching_client() {
+        let clients = vec![make_client("A", "aa:bb:cc:dd:ee:01", "10.0.0.1", "WIRED")];
+        let legacy_records = vec![
+            legacy(r#"{"_id":"1","mac":"aa:bb:cc:dd:ee:01","ip":"1.1.1.1"}"#),
+            legacy(r#"{"_id":"2","mac":"ff:ff:ff:ff:ff:ff","ip":"2.2.2.2"}"#),
+        ];
+        let rows = merge_rows(clients, legacy_records);
+        assert_eq!(rows.len(), 1);
+        assert_eq!(rows[0].live_ip(), Some("1.1.1.1"));
+    }
+
+    #[test]
+    fn to_json_emits_exactly_the_published_field_set() {
+        let rows = merge_rows(
+            vec![make_client("A", "aa:bb:cc:dd:ee:01", "10.0.0.1", "WIRED")],
+            vec![],
+        );
+        let json = rows[0].to_json();
+        let mut emitted: Vec<&str> = json
+            .as_object()
+            .unwrap()
+            .keys()
+            .map(|s| s.as_str())
+            .collect();
+        let mut published = crate::fields::names(crate::fields::CLIENTS_LIST);
+        emitted.sort_unstable();
+        published.sort_unstable();
+        assert_eq!(
+            emitted, published,
+            "clients list output must match the fields the schema publishes"
+        );
+    }
+
     // --- total_bytes ---
 
     #[test]

{unifi_cli-0.2.3 → unifi_cli-0.3.0}/src/commands/devices.rs

@@ -6,7 +6,8 @@ use crate::output::{OutputConfig, use_color};
 pub struct Pagination {
     pub limit: usize,
     pub offset: usize,
-    pub fields: Option<String>,
+    /// Field names already validated against `fields::DEVICES_LIST`.
+    pub fields: Option<Vec<String>>,
 }
 
 fn render_devices(devices: &[Device], out: &OutputConfig) {
@@ -146,10 +147,9 @@ pub async fn list(
                         "state": d.state,
                         "firmware": d.firmware_version,
                     });
-                    if let Some(ref fields_str) = pagination.fields {
-                        let keep: Vec<&str> = fields_str.split(',').map(str::trim).collect();
-                        let map = obj.as_object_mut().unwrap();
-                        map.retain(|k, _| keep.contains(&k.as_str()));
+                    if let Some(ref keep) = pagination.fields {
+                        let map = obj.as_object_mut().expect("device is a JSON object");
+                        map.retain(|k, _| keep.iter().any(|f| f == k));
                     }
                     obj
                 })

{unifi_cli-0.2.3 → unifi_cli-0.3.0}/src/commands/events.rs

@@ -6,7 +6,8 @@ use crate::output::{OutputConfig, use_color};
 pub struct Pagination {
     pub limit: usize,
     pub offset: usize,
-    pub fields: Option<String>,
+    /// Field names already validated against `fields::EVENTS_LIST`.
+    pub fields: Option<Vec<String>>,
 }
 
 pub async fn list(
@@ -33,10 +34,9 @@ pub async fn list(
                     "time": e.time,
                     "datetime": e.datetime,
                 });
-                if let Some(ref fields_str) = pagination.fields {
-                    let keep: Vec<&str> = fields_str.split(',').map(str::trim).collect();
-                    let map = obj.as_object_mut().unwrap();
-                    map.retain(|k, _| keep.contains(&k.as_str()));
+                if let Some(ref keep) = pagination.fields {
+                    let map = obj.as_object_mut().expect("event is a JSON object");
+                    map.retain(|k, _| keep.iter().any(|f| f == k));
                 }
                 obj
             })