yoto-nodejs-client 0.0.2 → 0.0.4

package/README.md

@@ -7,7 +7,15 @@
 [![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-7fffff?style=flat&labelColor=ff80ff)](https://github.com/neostandard/neostandard)
 [![Socket Badge](https://socket.dev/api/badge/npm/package/yoto-nodejs-client)](https://socket.dev/npm/package/yoto-nodejs-client)
 
-A comprehensive Node.js client for the [Yoto API][yoto-api] with automatic token refresh, MQTT device communication, and full TypeScript support.
+A comprehensive Node.js client for the [Yoto API][yoto-api] with automatic token refresh, MQTT device communication, stateful device management, and full TypeScript support.
+
+**Features:**
+- **YotoClient** - Low-level HTTP API client with automatic token refresh
+- **YotoDeviceModel** - Stateful device client combining HTTP + MQTT for unified, real time device state
+- **YotoAccount** - Multi-device account manager with automatic discovery and lifecycle management
+- Full TypeScript types
+- Real-time MQTT device control and monitoring
+- Debugging CLI tools for authentication and data inspection
 
 <p align="center">
   <img src="yoto.png" alt="Yoto" width="200">
@@ -19,6 +27,8 @@ npm install yoto-nodejs-client
 
 ## Usage
 
+### Basic API Client
+
 ```js
 import { YotoClient } from 'yoto-nodejs-client'
 
@@ -30,11 +40,16 @@ const deviceCodeResponse = await YotoClient.requestDeviceCode({
 console.log(`Visit ${deviceCodeResponse.verification_uri_complete}`)
 console.log(`Enter code: ${deviceCodeResponse.user_code}`)
 
-// Poll for token
-const tokenResponse = await YotoClient.exchangeToken({
-  grantType: 'urn:ietf:params:oauth:grant-type:device_code',
+// Wait for authorization (simplest approach - handles polling automatically)
+const tokenResponse = await YotoClient.waitForDeviceAuthorization({
   deviceCode: deviceCodeResponse.device_code,
-  clientId: 'your-client-id'
+  clientId: 'your-client-id',
+  initialInterval: deviceCodeResponse.interval * 1000,
+  expiresIn: deviceCodeResponse.expires_in,
+  onPoll: (result) => {
+    if (result.status === 'pending') process.stdout.write('.')
+    if (result.status === 'slow_down') console.log('\nSlowing down...')
+  }
 })
 
 // Create client with automatic token refresh
@@ -45,9 +60,9 @@ const client = new YotoClient({
   onTokenRefresh: async (event) => {
     // REQUIRED: Persist tokens when they refresh
     await saveTokens({
-      accessToken: event.accessToken,
-      refreshToken: event.refreshToken,
-      expiresAt: event.expiresAt
+      accessToken: event.updatedAccessToken,
+      refreshToken: event.updatedRefreshToken,
+      expiresAt: event.updatedExpiresAt
     })
   }
 })
@@ -84,6 +99,153 @@ await mqtt.setVolume(50)
 await mqtt.setAmbientHex('#FF0000')
 ```
 
+### YotoDeviceModel - Stateful Device Client
+
+```js
+import { YotoClient, YotoDeviceModel } from 'yoto-nodejs-client'
+
+// Create API client
+const client = new YotoClient({
+  clientId: 'your-client-id',
+  refreshToken: 'your-refresh-token',
+  accessToken: 'your-access-token',
+  onTokenRefresh: async (event) => {
+    await saveTokens(event)
+  }
+})
+
+// Get a device
+const { devices } = await client.getDevices()
+const device = devices[0]
+
+// Create stateful device client (manages HTTP + MQTT state)
+const deviceClient = new YotoDeviceModel(client, device, {
+  httpPollIntervalMs: 600000  // Background polling every 10 minutes
+})
+
+// Listen for status updates (from MQTT or HTTP)
+deviceClient.on('statusUpdate', (status, source, changedFields) => {
+  console.log(`Battery: ${status.batteryLevelPercentage}% (via ${source})`)
+  console.log(`Temperature: ${status.temperatureCelsius}°C`)
+  console.log(`Online: ${status.isOnline}`)
+  console.log('Changed fields:', changedFields)
+})
+
+// Listen for config changes
+deviceClient.on('configUpdate', (config, changedFields) => {
+  console.log('Config updated:', config.maxVolumeLimit)
+  console.log('Changed fields:', changedFields)
+})
+
+// Listen for playback events
+deviceClient.on('playbackUpdate', (playback, changedFields) => {
+  console.log(`Playing: ${playback.trackTitle}`)
+  console.log(`Position: ${playback.position}/${playback.trackLength}s`)
+  console.log('Changed fields:', changedFields)
+})
+
+// Listen for online/offline events
+deviceClient.on('online', (metadata) => {
+  if (metadata.reason === 'startup') {
+    console.log(`Device powered on (uptime: ${metadata.upTime}s)`)
+  } else {
+    console.log('Device came online')
+  }
+})
+
+deviceClient.on('offline', (metadata) => {
+  if (metadata.reason === 'shutdown') {
+    console.log(`Device shut down: ${metadata.shutDownReason}`)
+  }
+})
+
+// Start the device client (connects MQTT, starts background polling)
+await deviceClient.start()
+
+// Access current state
+console.log('Current status:', deviceClient.status)
+console.log('Current config:', deviceClient.config)
+console.log('Current playback:', deviceClient.playback)
+console.log('Device capabilities:', deviceClient.capabilities)
+
+// Control the device
+await deviceClient.updateConfig({ maxVolumeLimit: '14' })
+await deviceClient.sendCommand({ volume: 50 })
+
+// Stop when done
+await deviceClient.stop()
+```
+
+### Account Manager (Multiple Devices)
+
+```js
+import { YotoAccount } from 'yoto-nodejs-client'
+
+// Create account manager
+const account = new YotoAccount({
+  clientOptions: {
+    clientId: 'your-client-id',
+    refreshToken: 'your-refresh-token',
+    accessToken: 'your-access-token',
+    onTokenRefresh: async (event) => {
+      await saveTokens(event)
+    }
+  },
+  deviceOptions: {
+    httpPollIntervalMs: 600000  // Applied to all devices
+  }
+})
+
+// Listen for account events
+account.on('started', (metadata) => {
+  console.log(`Managing ${metadata.deviceCount} devices`)
+})
+
+
+
+// Listen for device-specific events from individual devices
+account.on('deviceAdded', (deviceId, deviceModel) => {
+  // Attach event listeners to each device as it's added
+  deviceModel.on('statusUpdate', (status, source) => {
+    console.log(`${deviceId} battery: ${status.batteryLevelPercentage}%`)
+  })
+
+  deviceModel.on('online', (metadata) => {
+    console.log(`${deviceId} came online`)
+  })
+
+  deviceModel.on('offline', (metadata) => {
+    console.log(`${deviceId} went offline`)
+  })
+})
+
+// Unified error handling
+account.on('error', (error, context) => {
+  console.error(`Error in ${context.source}:`, error.message)
+  if (context.deviceId) {
+    console.error(`Device: ${context.deviceId}`)
+  }
+})
+
+// Start managing all devices
+await account.start()
+
+// Access individual devices
+const device = account.getDevice('abc123')
+console.log('Device status:', device.status)
+console.log('Device config:', device.config)
+
+// Get all devices
+const allDevices = account.devices  // Map<deviceId, YotoDeviceModel>
+console.log('Total devices:', allDevices.size)
+
+// Refresh device list (add new, remove missing)
+await account.refreshDevices()
+
+// Stop all devices
+await account.stop()
+```
+
 ## API
 
 ### Authentication
@@ -122,9 +284,11 @@ Exchange authorization code, refresh token, or device code for access tokens.
 See [Yoto API: Token Exchange][api-token]
 
 ```js
+import { YotoClient, DEVICE_CODE_GRANT_TYPE } from 'yoto-nodejs-client'
+
 // Exchange device code
 const tokens = await YotoClient.exchangeToken({
-  grantType: 'urn:ietf:params:oauth:grant-type:device_code',
+  grantType: DEVICE_CODE_GRANT_TYPE,
   deviceCode: response.device_code,
   clientId: 'your-client-id'
 })
@@ -137,6 +301,103 @@ const refreshed = await YotoClient.exchangeToken({
 })
 ```
 
+#### `YotoClient.waitForDeviceAuthorization({ deviceCode, clientId, [initialInterval], [expiresIn], [onPoll] })`
+
+Wait for device authorization to complete with automatic polling. This is the **simplest approach** - just call it and await the result. It handles all polling logic internally including interval adjustments and timeout detection.
+
+Designed for CLI usage where you want to block until authorization completes. For UI implementations with custom progress feedback, use `pollForDeviceToken()` directly.
+
+- **deviceCode** - Device code from `requestDeviceCode()`
+- **clientId** - OAuth client ID
+- **initialInterval** - Initial polling interval in milliseconds (default: 5000)
+- **expiresIn** - Seconds until device code expires (for timeout detection)
+- **audience** - Audience for the token (default: 'https://api.yotoplay.com')
+- **onPoll** - Optional callback invoked after each poll attempt with the poll result
+
+Returns a promise that resolves to `YotoTokenResponse` on successful authorization.
+
+Throws `YotoAPIError` for unrecoverable errors (expired_token, access_denied, invalid_grant) or `Error` if device code expires.
+
+See [Yoto API: Token Exchange][api-token]
+
+```js
+import { YotoClient } from 'yoto-nodejs-client'
+
+// Simplest approach - just wait for tokens
+const deviceAuth = await YotoClient.requestDeviceCode({
+  clientId: 'your-client-id'
+})
+
+console.log(`Visit: ${deviceAuth.verification_uri_complete}`)
+console.log(`Code: ${deviceAuth.user_code}`)
+
+// This blocks until authorization completes (or fails)
+const tokens = await YotoClient.waitForDeviceAuthorization({
+  deviceCode: deviceAuth.device_code,
+  clientId: 'your-client-id',
+  initialInterval: deviceAuth.interval * 1000,
+  expiresIn: deviceAuth.expires_in,
+  onPoll: (result) => {
+    if (result.status === 'pending') process.stdout.write('.')
+    if (result.status === 'slow_down') console.log('\nSlowing down...')
+  }
+})
+
+console.log('Got tokens:', tokens)
+```
+
+#### `YotoClient.pollForDeviceToken({ deviceCode, clientId, [currentInterval], [audience] })`
+
+Poll for device authorization completion with automatic error handling (single poll attempt). This is a lower-level method that gives you control over the polling loop. Use `waitForDeviceAuthorization()` for a simpler approach.
+
+Non-blocking - returns immediately with poll result. Suitable for:
+- Manual polling loops in CLI applications
+- Server-side endpoints that poll on behalf of clients (e.g., Homebridge UI server)
+- Custom UI implementations with specific polling behavior
+
+- **deviceCode** - Device code from `requestDeviceCode()`
+- **clientId** - OAuth client ID
+- **currentInterval** - Current polling interval in milliseconds (default: 5000)
+- **audience** - Audience for the token (default: 'https://api.yotoplay.com')
+
+Returns a promise that resolves to one of:
+- `{ status: 'success', tokens: YotoTokenResponse }` - Authorization successful
+- `{ status: 'pending', interval: number }` - Still waiting for user authorization
+- `{ status: 'slow_down', interval: number }` - Polling too fast, use new interval
+
+Throws `YotoAPIError` for unrecoverable errors (expired_token, access_denied, invalid_grant, etc).
+
+See [Yoto API: Token Exchange][api-token]
+
+```js
+import { YotoClient } from 'yoto-nodejs-client'
+
+// Manual polling loop with full control
+const deviceAuth = await YotoClient.requestDeviceCode({
+  clientId: 'your-client-id'
+})
+
+let interval = deviceAuth.interval * 1000
+
+while (true) {
+  const result = await YotoClient.pollForDeviceToken({
+    deviceCode: deviceAuth.device_code,
+    clientId: 'your-client-id',
+    currentInterval: interval
+  })
+
+  if (result.status === 'success') {
+    console.log('Tokens:', result.tokens)
+    break
+  } else if (result.status === 'slow_down') {
+    interval = result.interval
+  }
+  
+  // Sleep
+  await new Promise(resolve => setTimeout(resolve, interval))
+}
+```
+
 #### `YotoClient.getAuthorizeUrl({ clientId, redirectUri, responseType, state, ...params })`
 
 Get authorization URL for browser-based OAuth flow. Returns a URL string to redirect users to.
@@ -156,9 +417,9 @@ Create a new Yoto API client with automatic token refresh.
 - **bufferSeconds** - Seconds before expiration to refresh (default: 30)
 - **userAgent** - Optional user agent string to identify your application
 - **defaultRequestOptions** - Optional default undici request options (dispatcher, timeouts, etc.) applied to all requests
-- **onRefreshStart** - Optional callback when refresh starts
-- **onRefreshError** - Optional callback for transient refresh errors
-- **onInvalid** - Optional callback when refresh token is permanently invalid
+- **onRefreshStart** - Optional callback when refresh starts. Console.logs by default.
+- **onRefreshError** - Optional callback for transient refresh errors. Console.error's by default.
+- **onInvalid** - Optional callback when refresh token is permanently invalid. Console.errors by default.
 
 ```js
 const client = new YotoClient({
@@ -171,16 +432,16 @@ const client = new YotoClient({
     headersTimeout: 10000,    // 10 second header timeout
     // dispatcher, signal, etc.
   },
-  onTokenRefresh: async ({ accessToken, refreshToken, expiresAt }) => {
+  onTokenRefresh: async ({ updatedAccessToken, updatedRefreshToken, updatedExpiresAt }) => {
     // Save to database, file, etc.
-    await db.saveTokens({ accessToken, refreshToken, expiresAt })
+    await db.saveTokens({ accessToken: updatedAccessToken, refreshToken: updatedRefreshToken, expiresAt: updatedExpiresAt })
   }
 })
 ```
 
 #### Request Options
 
-All API methods accept an optional `requestOptions` parameter that allows you to override the default undici request options for individual requests. This is useful for setting custom timeouts, using a specific dispatcher, or aborting requests.
+All API methods accept an optional [undici][undici] `requestOptions` parameter that allows you to override the default undici request options for individual requests. This is useful for setting custom timeouts, using a specific dispatcher, or aborting requests.
 
 ```js
 // Override timeout for a specific request
@@ -650,49 +911,280 @@ The MQTT client emits three types of messages:
 - `await mqtt.stopCard()` - Stop playback
 - `await mqtt.reboot()` - Reboot device
 
+### YotoDeviceModel - Stateful Device Client
+
+#### `new YotoDeviceModel(client, device, [options])`
+
+Create a stateful device client that manages device state primarily from MQTT with HTTP background sync.
+
+**Philosophy:**
+- MQTT is the primary source for all real-time status updates
+- MQTT connection is always maintained and handles its own reconnection
+- Device online/offline state is tracked by MQTT activity and explicit shutdown messages
+- HTTP background polling runs every 10 minutes to sync config+status regardless of online state
+- HTTP status updates emit offline events if device state changes to offline
+
+**Parameters:**
+- `client` - YotoClient instance
+- `device` - Device object from `getDevices()`
+- `options.httpPollIntervalMs` - Background HTTP polling interval (default: 600000ms / 10 minutes)
+- `options.mqttOptions` - MQTT.js client options to pass through
+
+**Lifecycle:**
+- `await deviceClient.start()` - Start device client (connects MQTT, starts polling)
+- `await deviceClient.stop()` - Stop device client (disconnects MQTT, stops polling)
+- `await deviceClient.restart()` - Restart device client
+
+**State Accessors:**
+- `deviceClient.device` - Device information
+- `deviceClient.status` - Current device status (normalized from HTTP/MQTT)
+- `deviceClient.config` - Device configuration
+- `deviceClient.shortcuts` - Button shortcuts
+- `deviceClient.playback` - Current playback state
+- `deviceClient.capabilities` - Hardware capabilities (sensors, nightlight support, etc.)
+- `deviceClient.nightlight` - Nightlight info: { value, name, supported }
+- `deviceClient.initialized` - Whether device has been initialized
+- `deviceClient.running` - Whether device client is currently running
+- `deviceClient.mqttConnected` - MQTT connection status
+- `deviceClient.deviceOnline` - Device online status
+- `deviceClient.mqttClient` - Underlying MQTT client instance (or null)
+
+**Device Control:**
+- `await deviceClient.refreshConfig()` - Refresh config from HTTP API
+- `await deviceClient.updateConfig(configUpdate)` - Update device configuration
+- `await deviceClient.sendCommand(command)` - Send device command via HTTP
+
+**Events:**
+- `started(metadata)` - Device client started, passes metadata object with device, config, shortcuts, status, playback, initialized, running
+- `stopped()` - Device client stopped
+- `statusUpdate(status, source, changedFields)` - Status changed, passes (status, source, changedFields). Source is 'http', 'mqtt', or 'mqtt-event'
+- `configUpdate(config, changedFields)` - Configuration changed, passes (config, changedFields)
+- `playbackUpdate(playback, changedFields)` - Playback state changed, passes (playback, changedFields)
+- `online(metadata)` - Device came online, passes metadata with reason and optional upTime
+- `offline(metadata)` - Device went offline, passes metadata with reason and optional shutDownReason or timeSinceLastSeen
+- `mqttConnected()` - MQTT client connected
+- `mqttDisconnected()` - MQTT client disconnected
+- `error(error)` - Error occurred, passes error
+
+**Static Properties & Methods:**
+- `YotoDeviceModel.NIGHTLIGHT_COLORS` - Map of nightlight color hex codes to official color names
+- `YotoDeviceModel.getNightlightColorName(colorValue)` - Get official color name for a nightlight value
+
+```js
+import { YotoClient, YotoDeviceModel } from 'yoto-nodejs-client'
+
+const client = new YotoClient({ /* ... */ })
+const { devices } = await client.getDevices()
+
+const deviceClient = new YotoDeviceModel(client, devices[0], {
+  httpPollIntervalMs: 300000  // Poll every 5 minutes
+})
+
+deviceClient.on('statusUpdate', (status, source, changedFields) => {
+  console.log(`Battery: ${status.batteryLevelPercentage}% (${source})`)
+  console.log('Changed fields:', changedFields)
+})
+
+deviceClient.on('online', (metadata) => {
+  console.log('Device online:', metadata.reason)
+})
+
+await deviceClient.start()
+
+// Access state
+console.log('Temperature:', deviceClient.status.temperatureCelsius)
+console.log('Has temp sensor:', deviceClient.capabilities.hasTemperatureSensor)
+console.log('Nightlight:', deviceClient.nightlight)  // { value, name, supported }
+
+// Use static nightlight utilities
+console.log('Available colors:', YotoDeviceModel.NIGHTLIGHT_COLORS)
+console.log('Color name:', YotoDeviceModel.getNightlightColorName('0x643600'))
+
+// Control device
+await deviceClient.updateConfig({ maxVolumeLimit: '14' })
+
+await deviceClient.stop()
+```
+
+### Account Manager
+
+#### `new YotoAccount({ clientOptions, deviceOptions })`
+
+Create an account manager that automatically discovers and manages all devices for a Yoto account.
+
+**Parameters:**
+- `clientOptions` - YotoClient constructor options (clientId, refreshToken, accessToken, onTokenRefresh, etc.)
+- `deviceOptions` - YotoDeviceModel options applied to all devices (httpPollIntervalMs, mqttOptions)
+
+**Lifecycle:**
+- `await account.start()` - Start account (creates client, discovers devices, starts all device clients)
+- `await account.stop()` - Stop account (stops all device clients gracefully)
+- `await account.restart()` - Restart account
+- `await account.refreshDevices()` - Refresh device list (add new, remove missing)
+
+**State Accessors:**
+- `account.client` - Underlying YotoClient instance
+- `account.devices` - Map of all device models (Map<deviceId, YotoDeviceModel>)
+- `account.getDevice(deviceId)` - Get specific device model
+- `account.getDeviceIds()` - Get array of all device IDs
+- `account.running` - Whether account is currently running
+- `account.initialized` - Whether account has been initialized
+
+**Events:**
+- `started(metadata)` - Account started (metadata: { deviceCount, devices })
+- `stopped()` - Account stopped
+- `deviceAdded(deviceId, deviceModel)` - Device was added
+- `deviceRemoved(deviceId)` - Device was removed
+- `error(error, context)` - Error occurred (context: { source, deviceId, operation })
+
+**Note:** To listen to individual device events (statusUpdate, configUpdate, playbackUpdate, online, offline, mqttConnected, mqttDisconnected, etc.), access the device models directly via `account.devices` or `account.getDevice(deviceId)` and attach listeners to them.
+
+```js
+import { YotoAccount } from 'yoto-nodejs-client'
+
+const account = new YotoAccount({
+  clientOptions: {
+    clientId: 'your-client-id',
+    refreshToken: 'your-refresh-token',
+    accessToken: 'your-access-token',
+    onTokenRefresh: async (event) => {
+      await saveTokens(event)
+    }
+  },
+  deviceOptions: {
+    httpPollIntervalMs: 600000  // 10 minutes
+  }
+})
+
+// Account-level error handling
+account.on('error', (error, context) => {
+  console.error(`Error in ${context.source}:`, error.message)
+})
+
+// Listen to device added events
+account.on('deviceAdded', (deviceId, deviceModel) => {
+  console.log(`Device ${deviceId} added`)
+  
+  // Attach listeners to individual devices
+  deviceModel.on('statusUpdate', (status, source) => {
+    console.log(`${deviceId} battery: ${status.batteryLevelPercentage}%`)
+  })
+  
+  deviceModel.on('online', (metadata) => {
+    console.log(`${deviceId} came online (${metadata.reason})`)
+  })
+  
+  deviceModel.on('offline', (metadata) => {
+    console.log(`${deviceId} went offline (${metadata.reason})`)
+  })
+})
+
+await account.start()
+
+// Access individual devices and attach listeners
+const device = account.getDevice('abc123')
+console.log('Device battery:', device.status.batteryLevelPercentage)
+
+// Listen to specific device events
+device.on('playbackUpdate', (playback) => {
+  console.log('Now playing:', playback.currentCardTitle)
+})
+
+// Iterate all devices and attach listeners
+for (const [deviceId, deviceModel] of account.devices) {
+  console.log(`${deviceId}: ${deviceModel.status.batteryLevelPercentage}%`)
+  
+  deviceModel.on('configUpdate', (config) => {
+    console.log(`${deviceId} config updated:`, config.name)
+  })
+}
+
+await account.stop()
+```
+
 ## CLI Tools
 
-The library includes CLI tools for authentication and data inspection:
+The library includes CLI tools for authentication and data inspection. After installing the package, these commands are available globally:
 
 ### Authentication
 
 ```bash
 # Get initial tokens (device flow)
-node bin/auth.js --output .env
+yoto-auth --output .env
+# or: node bin/auth.js --output .env
 
-# Refresh tokens
-node bin/refresh-token.js
+# Refresh existing tokens
+yoto-refresh-token
+# or: node bin/refresh-token.js
 
-# Show token info
-node bin/token-info.js
+# Show token info and inspect JWT contents
+yoto-token-info
+# or: node bin/token-info.js
 ```
 
-### Data Inspection
+### Devices
 
 ```bash
 # List all devices
-node bin/devices.js
+yoto-devices
+# or: node bin/devices.js
 
 # Get device details with config
-node bin/devices.js --device-id abc123
+yoto-devices --device-id abc123
 
 # Get device status only
-node bin/devices.js --device-id abc123 --status
+yoto-devices --device-id abc123 --status
 
 # Connect to MQTT and listen for messages
-node bin/devices.js --device-id abc123 --mqtt
+yoto-devices --device-id abc123 --mqtt
 
 # Sample MQTT messages for 10 seconds
-node bin/devices.js --device-id abc123 --mqtt --mqtt-stop-after-seconds 10
+yoto-devices --device-id abc123 --mqtt --mqtt-timeout 10
+
+# Use YotoDeviceModel to monitor device (HTTP + MQTT)
+yoto-device-model --device-id abc123
 
+# Interactive TUI for device control (Prototype/WIP/Unpublished)
+yoto-device-tui --device-id abc123
+```
+
+### Content
+
+```bash
 # List all MYO content
-node bin/content.js
+yoto-content
+# or: node bin/content.js
 
 # Get specific card details
-node bin/content.js --card-id 5WsQg
+yoto-content --card-id 5WsQg
 
 # Get card with playable URLs
-node bin/content.js --card-id 5WsQg --playable
+yoto-content --card-id 5WsQg --playable
+```
+
+### Family Library Groups
+
+```bash
+# List all family library groups
+yoto-groups
+# or: node bin/groups.js
+
+# Get specific group details
+yoto-groups --group-id abc123
+```
+
+### Icons
+
+```bash
+# List both public and user icons
+yoto-icons
+# or: node bin/icons.js
+
+# List only public Yoto icons
+yoto-icons --public
+
+# List only user custom icons
+yoto-icons --user
 ```
 
 ## See also
@@ -734,3 +1226,4 @@ MIT
 [api-upload-icon]: https://yoto.dev/api/uploadcustomicon/
 [api-audio-upload]: https://yoto.dev/api/getanuploadurl/
 [api-cover-image]: https://yoto.dev/api/uploadcoverimage/
+[undici]: https://undici.nodejs.org/#/docs/api/Client.md