manage-devices

name	manage-devices
description	Manage Webex Calling devices using wxcli CLI commands: phones (MPP, ATA, room devices), DECT networks, workspaces, activation codes, device settings, line key templates (BLF, speed dials, line key layout), hot desking members, and device tags. Guides the user from prerequisites through provisioning, activation, configuration, deletion, and verification. Use for: create, provision, activate, configure, delete, remove, decommission, or list devices and workspaces. NOT for: PhoneOS/RoomOS config keys or xAPI commands (use device-platform skill).
allowed-tools	Read, Grep, Glob, Bash
argument-hint	["device-operation"]

Manage Devices Workflow

Checkpoint — do NOT proceed until you can answer these:

1. What is the correct order for DECT provisioning? (Answer: Create DECT network → add base stations (real Cisco MACs required) → add handsets with line assignments.)
2. How do you generate an activation code for a device? (Answer: Use wxcli devices create-activation-code — the device must exist first via wxcli devices create.)

If you cannot answer both, you skipped reading this skill. Go back and read it.

Step 1: Load references and verify commands

1. Read docs/reference/devices-core.md for device CRUD, activation codes, MAC provisioning, line key templates, device settings
2. Read docs/reference/devices-dect.md for DECT networks, base stations, handsets, hot desking
3. Read docs/reference/devices-workspaces.md for workspace creation, workspace device assignment, workspace call settings

Mandatory --help verification: Before constructing any wxcli command, run wxcli <group> --help to verify the subcommand exists, then wxcli <group> <subcommand> --help to verify the exact flags. Do NOT rely on examples in this skill or reference docs — the CLI is auto-generated and flag names may differ from what documentation suggests. Common traps:

• validate-a-list has NO --macs flag and NO --output flag — use --json-body '{"macs":["..."]}' (always outputs JSON)
• create-base-stations has NO --base-station-macs flag — use --json-body '{"baseStationMacs":["..."]}'
• Person-level hoteling is wxcli device-settings update-hoteling — NOT wxcli user-call-settings (that group does not exist in the CLI; the registered group is user-settings)
• Hoteling read/write split: UPDATE is device-settings update-hoteling, but READ/VERIFY is user-settings show-hoteling — different groups! There is no show-hoteling in device-settings.
• LKT delete is wxcli device-settings delete TEMPLATE_ID — NOT delete-line-key-templates (that command doesn't exist)
• create-apply-line-key-template has named flags --action and --template-id — prefer these over --json-body for simple applies
• device-dynamic-settings get-customer-device / get-location-device / get-device-dynamic are POST-under-the-hood (they call .../actions/getSettings/invoke). They take --json-body '{"tags":["..."]}' and have NO --output flag — do not append -o json to them
• device-dynamic-settings update (per-device) vs create (org/location bulk job) — create is the bulk writer despite the name; update targets a single DEVICE_ID
• workspace-locations and locations share all 10 command names (list, create, show, update, delete, list-floors, create-floors, show-floors, update-floors, delete-floors). They are different APIs on different endpoints — see Step 6g before using either

Step 2: Verify auth token

Before any API calls, confirm the user has a working auth token:

wxcli whoami

If this fails, stop and resolve authentication first (wxcli configure). Required scopes vary by operation:

Operation	Read Scope	Write Scope
Cloud device CRUD, tags	spark-admin:devices_read	spark-admin:devices_write
Activation codes	spark-admin:devices_read	spark-admin:devices_write + identity:one_time_password
Telephony device config (members, settings, line keys, layout)	spark-admin:telephony_config_read	spark-admin:telephony_config_write
Workspaces	spark-admin:workspaces_read	spark-admin:workspaces_write
DECT networks, base stations, handsets	spark-admin:telephony_config_read	spark-admin:telephony_config_write

Step 3: Identify which device operation to perform

Ask the user what they want to do. Present this decision matrix if they are unsure:

Need	Operation	CLI Group
Add a Cisco MPP phone or ATA by MAC address	Create device by MAC	wxcli devices
Generate a code for a phone to self-register	Activation code	wxcli devices
View/manage devices in the org	List/show/delete devices	wxcli devices
Assign lines, shared lines, or members to a phone	Device members	wxcli device-settings
Configure line keys, speed dials, BLF monitoring	Line key templates / layout	wxcli device-settings
Change phone display, ringtone, or device-level settings	Device settings	wxcli device-settings
Set up a wireless DECT phone system	DECT network	wxcli dect-devices
Create a conference room or lobby phone workspace	Workspace	wxcli workspaces
Allow users to temporarily use a shared phone	Hot desking	wxcli hot-desk / wxcli hot-desking-portal
Validate MAC addresses before provisioning	MAC validation	wxcli device-settings
Push a phone setting (tag) to every device of a model, org-wide or per-location	Dynamic settings	wxcli device-dynamic-settings
Discover which settings/tags a phone model actually supports	Dynamic settings	wxcli device-dynamic-settings
Track/troubleshoot a bulk settings rollout job	Dynamic settings jobs	wxcli device-dynamic-settings
Manage legacy Workspaces-API locations (lat/long) and building floors	Workspace locations	wxcli workspace-locations

Not a hardware operation? For RoomOS software configuration, workspace personalization, or xAPI commands (dial, volume, standby, room analytics), use the device-platform skill instead.

Step 4: Prerequisites

Before any device operation, verify these exist and gather operation-specific requirements.

4a. Location exists

All devices and workspaces are location-scoped. Confirm the target location:

wxcli locations list --output json

Capture the location_id for the target location.

4b. Check device configuration mode (for settings operations)

If the user's request involves reading or changing device settings (not just CRUD, line assignment, or activation), determine which API surface the target device uses:

1. Look up the device:

   wxcli devices list --mac MAC_ADDRESS --output json
   

2. Check the product field in the response. Route based on model family and operation type:

   • 9800-series (product contains "9811", "9821", "9841", "9851", "9861", or "9871"):
     • Device-level settings (show-settings-devices, update-settings-devices): These 404 on 9800-series. Redirect to the device-platform skill for PhoneOS config keys (ringtone, standby, display, wallpaper, line labels, etc.). NOTE: 9800-series runs PhoneOS, NOT RoomOS. PhoneOS is RoomOS-derived but distinct — do not call these "RoomOS keys" or call 9800 devices "RoomOS devices".
     • Line Key Templates (create, list, show, update, delete, apply): Stay in this skill. Works with model "Cisco 98xx".
     • Device member management (list members, update members/ports): Stay in this skill. Works normally.
     • Person-level device settings (show-settings-devices-3): Stay in this skill. Works (limited fields).
   • Room, Board, Desk series: Redirect to device-platform skill for all configuration.
   • MPP 68xx, 78xx, 88xx, ATA: Continue with device-settings commands in this skill.

Why this matters: The 9800-series phones are productType: phone but run PhoneOS (RoomOS-derived). Only device-level settings endpoints (show-settings-devices, update-settings-devices) fail on 9800-series with 404. Line key templates, member management, and person-level settings work fine through the telephony config API. Do not blanket-redirect all 9800-series operations — route by operation type.

See docs/reference/devices-core.md Section 5a (Device Settings API Router) for the full routing table.

4c. User or workspace exists (for device assignment)

Devices must be assigned to a person or workspace:

# List calling-enabled users
wxcli users list --calling-data true --output json

# List workspaces
wxcli workspaces list --output json

4d. Phone numbers/extensions available

wxcli numbers list --location-id LOCATION_ID --output json

4e. MPP/ATA phone prerequisites

Requirement	Details
Valid MAC address	12 hex characters (e.g., AABBCCDDEEFF). Validate with wxcli device-settings validate-a-list --json-body '{"macs":["AABBCCDDEEFF"]}'
Target person/workspace	Must exist before device creation
Device model	Must be in supported catalog
SIP password	Only for 3rd-party (non-Cisco) devices

4f. Activation code prerequisites

Requirement	Details
Target person/workspace	Must exist
Model parameter	Required for phones; optional for RoomOS collaboration devices

4g. DECT prerequisites

Requirement	Details
Location	Must exist
Base station MAC addresses	Physical hardware MAC required
Dependency chain	Network --> Base Station(s) --> Handset(s). Cannot skip steps

4h. Workspace device prerequisites

Requirement	Details
Workspace	Must be created first with Webex Calling enabled and a location assigned
location_id and supported_devices	Immutable after creation -- set correctly on creation
Hot-desk-only workspaces	Cannot have phoneNumber, extension, calendar, or deviceHostedMeetings set

4i. Device settings prerequisites

Requirement	Details
Line key template	Device model must match. Template applies org-wide or by location/tag filter
Device settings GET/PUT	deviceModel parameter is required

4j. Hot desking prerequisites

Requirement	Details
Workspace side	hotdeskingStatus must be on
Person side	Hoteling must be enabled on person's profile via wxcli device-settings update-hoteling

---

Step 5: Build and present deployment plan -- [SHOW BEFORE EXECUTING]

Before executing any commands, present the full plan to the user:

DEPLOYMENT PLAN
===============
Operation: [device operation type]
Location: [name] ([location_id])
Target: [person/workspace name] ([id])

Device Details:
  Type: [MPP phone / ATA / DECT / Room device]
  Model: [model name]
  MAC: [mac_address or "Activation code"]
  Assignment: [person / workspace]

Configuration:
  [Operation-specific settings listed here]

Prerequisites verified:
  [check] Location exists
  [check] Person/workspace exists
  [check] MAC address validated (if applicable)
  [check] [Operation-specific prereqs]

Commands to execute:
  wxcli [group] [command] ...
  wxcli device-settings apply-changes-for DEVICE_ID (if settings changed)

Proceed? (yes/no)

Wait for user confirmation before executing.

Step 6: Execute via wxcli

Run the commands in order. For multi-step operations (e.g., workspace + device + settings), execute sequentially.

Handle errors explicitly:

• 401/403: Token expired or insufficient scopes -- run wxcli configure to re-authenticate
• 400 "MAC address unavailable": MAC already registered to another device -- check with wxcli device-settings validate-a-list
• 400 "Model not supported": Use wxcli device-settings list-supported-devices-dect-networks or check supported catalog
• 409: Name or resource conflict -- ask user for alternate

Always call apply-changes-for after updating device settings, members, or layout to push configuration to the physical device.

6a. Device lifecycle -- Create, Activate, Configure, Manage

List and discover devices:

# List all devices in the org
wxcli devices list --output json

# Show details for a specific device
wxcli devices show DEVICE_ID --output json

Create a device by MAC address:

Collect from user:

Parameter	Required	Notes
MAC address	Yes	12 hex characters (e.g., AABBCCDDEEFF)
Person ID or Workspace ID	Yes	Who/what the device is assigned to
Model	Yes	Must be from the supported devices catalog
Password	Only for 3rd-party	SIP password for non-Cisco devices

# Validate MAC first (no --macs flag; use --json-body)
wxcli device-settings validate-a-list --json-body '{"macs":["AABBCCDDEEFF"]}'

# Create the device
wxcli devices create --mac AABBCCDDEEFF --workspace-id WORKSPACE_ID --model "DMS Cisco 8845"

Generate activation code:

Activation codes allow a phone to self-register when the user enters the code on the phone screen.

# For a workspace device
wxcli devices create-activation-code --workspace-id WORKSPACE_ID

# For a person's device (model required for phones)
wxcli devices create-activation-code --person-id PERSON_ID --model "DMS Cisco 8845"

The code expires after a set period. The user enters it on the phone's activation screen, and the device auto-registers with Webex Calling.

Activation codes provide a zero-touch provisioning workflow:

1. Admin generates code via wxcli devices create-activation-code
2. Code is communicated to the on-site technician or end user
3. User enters code on the phone's activation screen
4. Phone auto-registers with Webex Calling, downloads config, and becomes operational
5. Code expires after the configured period (typically 7 days)

NOTE: Activation codes for phones require a model parameter. RoomOS collaboration devices do not require a model.

Delete a device:

wxcli devices delete DEVICE_ID

WARNING: Deleting a device deregisters it. The device must be reactivated (new activation code or re-provisioned by MAC) to be reused.

Update device tags:

wxcli devices update DEVICE_ID --op replace --path tags --value '["lobby","floor-2"]'

--op is add, remove, or replace; --path only supports tags.

NOTE: Tag operations use JSON Patch format. The CLI handles this internally. Tags are useful for filtering devices in bulk operations (e.g., apply line key templates by tag).

6b. DECT workflow -- Network, Base Station, Handset (strict dependency)

DECT provisioning follows a strict dependency chain. Each step depends on the previous one completing first.

DECT Network --> Base Station(s) --> Handset(s)
   (step 1)        (step 2)          (step 3)

You cannot skip steps. A base station requires a network. A handset requires a base station.

Create a DECT network:

Collect from user:

Parameter	Required	Notes
Location ID	Yes	Positional argument
Name	Yes	Unique per location, 1-40 characters
Model	Yes	DMS Cisco DBS110 (single-cell, 1 base, 30 lines) or DMS Cisco DBS210 (multi-cell, up to 250 bases, 1000 lines)
Default access code enabled	Yes	true = shared 4-digit code; false = auto-generated per-handset
Default access code	If enabled	4 numeric digits, unique within the location
Display name	No	Shown on handsets, max 11 characters

# Create DECT network
wxcli dect-devices create LOCATION_ID \
  --name "Building A DECT" \
  --model "DMS Cisco DBS210" \
  --default-access-code-enabled \
  --default-access-code 1234 \
  --display-name "Bldg A"

# List DECT networks
wxcli dect-devices list --output json

# Show network details
wxcli dect-devices show LOCATION_ID DECT_NETWORK_ID --output json

Add base stations:

Base stations require MAC addresses from the physical DECT base station hardware.

# Create base station(s) by MAC (no --base-station-macs flag; use --json-body)
wxcli dect-devices create-base-stations LOCATION_ID DECT_NETWORK_ID \
  --json-body '{"baseStationMacs":["AABBCCDDEEFF"]}'

# List base stations
wxcli dect-devices list-base-stations LOCATION_ID DECT_NETWORK_ID --output json

# Show base station details
wxcli dect-devices show-base-stations LOCATION_ID DECT_NETWORK_ID BASE_STATION_ID --output json

Add handsets:

Each handset supports up to 2 lines. Line 1 must be a person or workspace (place). Line 2 can also be a virtual line.

# Search for available members to assign to handsets
wxcli dect-devices list-available-members --output json

# Add a single handset
wxcli dect-devices create-handsets LOCATION_ID DECT_NETWORK_ID \
  --line1-member-id PERSON_ID \
  --custom-display-name "Reception"

# Add handsets in bulk (up to 50)
wxcli dect-devices create-bulk LOCATION_ID DECT_NETWORK_ID --json-body '{
  "items": [
    {"line1MemberId": "PERSON_ID_1", "customDisplayName": "User 1"},
    {"line1MemberId": "PERSON_ID_2", "customDisplayName": "User 2"}
  ]
}'

# List handsets
wxcli dect-devices list-handsets LOCATION_ID DECT_NETWORK_ID --output json

# Update handset line assignment
wxcli dect-devices update-handsets LOCATION_ID DECT_NETWORK_ID HANDSET_ID \
  --line1-member-id NEW_PERSON_ID \
  --custom-display-name "Updated Name"

DECT serviceability password:

# Check password status
wxcli dect-devices show-serviceability-password LOCATION_ID DECT_NETWORK_ID --output json

# Generate and enable (WARNING: may reboot entire DECT network)
wxcli dect-devices generate-and-enable LOCATION_ID DECT_NETWORK_ID

DECT association queries:

# DECT networks associated with a person
wxcli dect-devices list-dect-networks-people PERSON_ID --output json

# DECT networks associated with a workspace
wxcli dect-devices list-dect-networks-workspaces WORKSPACE_ID --output json

6c. Workspace devices -- Create workspace, assign device, configure settings

Create a Webex Calling workspace:

Collect from user:

Parameter	Required	Notes
Display name	Yes	Workspace name
Location ID	Yes	Cannot be changed after creation
Supported devices	Yes	phones (MPP) or collaborationDevices (Room/Board/Desk). Cannot be changed after creation
Extension or phone number	Yes (one of)	Not applicable for hot-desk-only workspaces
Workspace type	No	desk, meetingRoom, huddle, focus, open, other
Hotdesking status	No	on or off
Calling license ID	No	Auto-assigned from active subscriptions if omitted

# Create a workspace
wxcli workspaces create --json-body '{
  "displayName": "Lobby Phone",
  "locationId": "LOCATION_ID",
  "type": "desk",
  "supportedDevices": "phones",
  "hotdeskingStatus": "off",
  "calling": {
    "type": "webexCalling",
    "webexCalling": {
      "extension": "2001",
      "locationId": "LOCATION_ID"
    }
  }
}'

# List workspaces
wxcli workspaces list --output json

# Show workspace details
wxcli workspaces show WORKSPACE_ID --output json

# Get workspace capabilities
wxcli workspaces show-capabilities WORKSPACE_ID --output json

Assign a device to the workspace:

After creating the workspace, assign a device using either MAC address or activation code:

# Option 1: Create device by MAC and assign to workspace
wxcli devices create --mac AABBCCDDEEFF --workspace-id WORKSPACE_ID --model "DMS Cisco 8845"

# Option 2: Generate activation code for the workspace
wxcli devices create-activation-code --workspace-id WORKSPACE_ID

List workspace devices:

# List telephony devices assigned to a workspace
wxcli device-settings list-devices-workspaces WORKSPACE_ID --output json

Configure workspace call settings:

Workspace call settings mirror person call settings. Use wxcli workspace-settings:

# Call forwarding
wxcli workspace-settings show WORKSPACE_ID --output json
wxcli workspace-settings update WORKSPACE_ID --json-body '{"callForwarding": {"always": {"enabled": true, "destination": "[phone]"}}}'

# Call waiting
wxcli workspace-settings show-call-waiting WORKSPACE_ID --output json
wxcli workspace-settings update-call-waiting WORKSPACE_ID --enabled

# Caller ID
wxcli workspace-settings list WORKSPACE_ID --output json

# Monitoring (BLF)
wxcli workspace-settings list-monitoring WORKSPACE_ID --output json

# DND
wxcli workspace-settings show-do-not-disturb WORKSPACE_ID --output json
wxcli workspace-settings update-do-not-disturb WORKSPACE_ID --enabled

# Voicemail
wxcli workspace-settings show-voicemail WORKSPACE_ID --output json

Delete a workspace:

wxcli workspaces delete WORKSPACE_ID

WARNING: Deleting a workspace also deletes all associated devices. Those devices must be reactivated to be reused.

6d. Device settings configuration

Device members (line assignment):

Manage which users/lines appear on a phone:

# Get current members on a device
wxcli device-settings list DEVICE_ID --output json

# Search for available members to add as shared lines
wxcli device-settings list-available-members DEVICE_ID --output json

# Update members (add shared line appearance)
# IMPORTANT: every member entry MUST include lineWeight and primaryOwner — omitting either returns 400
wxcli device-settings update DEVICE_ID --json-body '{
  "members": [
    {"id": "PRIMARY_PERSON_ID", "port": 1, "lineType": "PRIMARY", "primaryOwner": true, "lineWeight": 1},
    {"id": "SHARED_PERSON_ID", "port": 2, "lineType": "SHARED_LINE", "primaryOwner": false, "lineWeight": 1}
  ]
}'

# Apply changes to push config to the physical device
wxcli device-settings apply-changes-for DEVICE_ID

Device-level settings (MPP/ATA):

# Get device settings (model required)
wxcli device-settings show-settings-devices DEVICE_ID --device-model "DMS Cisco 8845" --output json

# Update device settings
wxcli device-settings update-settings-devices DEVICE_ID --json-body '{
  "customEnabled": true,
  "customizations": {"mpp": {"displayNameFormat": "PERSON_LAST_THEN_FIRST_NAME"}}
}'

# Get person-level device settings (compression)
wxcli device-settings show-settings-devices-3 PERSON_ID --output json

# Get workspace-level device settings (compression)
wxcli device-settings show-settings-devices-4 WORKSPACE_ID --output json

# Get location-level device settings
wxcli device-settings show-settings-devices-1 LOCATION_ID --output json

# Get org-level device settings
wxcli device-settings show-settings-devices-2 --output json

Line key templates:

Line key templates define the button layout for phone models org-wide:

# List existing templates
wxcli device-settings list-line-key-templates --output json

# Create a template
wxcli device-settings create --json-body '{
  "templateName": "Standard Layout",
  "deviceModel": "DMS Cisco 8845",
  "lineKeys": [
    {"lineKeyIndex": 1, "lineKeyType": "PRIMARY_LINE"},
    {"lineKeyIndex": 2, "lineKeyType": "MONITOR"},
    {"lineKeyIndex": 3, "lineKeyType": "SPEED_DIAL", "lineKeyLabel": "Front Desk", "lineKeyValue": "1000"},
    {"lineKeyIndex": 4, "lineKeyType": "OPEN"}
  ]
}'

# Preview how many devices would be affected
wxcli device-settings preview-apply-line --action APPLY_TEMPLATE --template-id TEMPLATE_ID

# Apply template to devices (has named flags — simpler than --json-body)
wxcli device-settings create-apply-line-key-template --action APPLY_TEMPLATE --template-id TEMPLATE_ID

# Check apply job status
wxcli device-settings list-apply-line-key-template --output json
wxcli device-settings show-apply-line-key-template JOB_ID --output json

Line key types:

Type	Description
PRIMARY_LINE	User's primary line
SHARED_LINE	Shared line appearance
MONITOR	BLF (busy lamp field) monitoring
CALL_PARK_EXTENSION	Dedicated call park button
SPEED_DIAL	Speed dial (requires label + value)
OPEN	Available for user self-configuration
CLOSED	Locked/unavailable
MODE_MANAGEMENT	Operating mode control

Device layout (per-device customization):

# Get current device layout
wxcli device-settings list-layout DEVICE_ID --output json

# Update layout
wxcli device-settings update-layout DEVICE_ID --json-body '{
  "layoutMode": "CUSTOM",
  "lineKeys": [
    {"lineKeyIndex": 1, "lineKeyType": "PRIMARY_LINE"},
    {"lineKeyIndex": 2, "lineKeyType": "SPEED_DIAL", "lineKeyLabel": "Lobby", "lineKeyValue": "2000"}
  ]
}'

Background images:

# List org background images
wxcli device-settings list-background-images --output json

# Upload a background image to a device — no CLI (multipart upload, generator cannot render)
# Raw HTTP fallback: POST /telephony/config/devices/{deviceId}/actions/backgroundImageUpload/invoke (multipart/form-data)

# Delete background images — deletes ALL of them. The API scopes this with a
# request body, which the generator does not render for DELETE verbs (known
# issue #21), so the CLI cannot target individual images.
wxcli device-settings delete-background-images --force

# Delete specific images — no CLI. Raw HTTP fallback:
# DELETE /telephony/config/devices/backgroundImages
#   {"backgroundImages": [{"fileName": "logo.png", "forceDelete": true}]}

MAC address validation:

wxcli device-settings validate-a-list --json-body '{"macs":["AABBCCDDEEFF","112233445566"]}'

States: AVAILABLE, UNAVAILABLE, DUPLICATE_IN_LIST, INVALID

6e. Hot desking configuration

Hot desking allows users to temporarily sign into a shared workspace phone and use it as their own.

Workspace side: enable hot desking:

When creating a workspace, set hotdeskingStatus to on. For hot-desk-only workspaces, do not set phoneNumber, extension, calendar, or deviceHostedMeetings.

Person side: enable hoteling:

Use wxcli device-settings update-hoteling PERSON_ID --json-body '{"hoteling":{"enabled":true}}' to enable hoteling on a person's profile. Do NOT use wxcli user-call-settings — that CLI group does not exist (its orphan source file was deleted at the 2026-07-01 spec sync; the registered group is user-settings).

Hoteling read/write asymmetry: The update command is wxcli device-settings update-hoteling, but the read/verify command is wxcli user-settings show-hoteling PERSON_ID — they are in different CLI groups. There is no show-hoteling in device-settings.

Manage hot desk sessions:

# List active hot desk sessions
wxcli hot-desk list --output json

# List sessions for a specific person
wxcli hot-desk list --person-id PERSON_ID --output json

# List sessions for a specific workspace
wxcli hot-desk list --workspace-id WORKSPACE_ID --output json

# End a hot desk session
wxcli hot-desk delete SESSION_ID

Voice portal hot desking sign-in:

# View location-level voice portal hot desking settings
wxcli hot-desking-portal show LOCATION_ID --output json

# Update location-level settings
wxcli hot-desking-portal update LOCATION_ID --json-body '{...}'

# View user-level guest hot desking settings
wxcli hot-desking-portal show-guest PERSON_ID --output json

6f. Device dynamic settings (fleet-wide phone settings by tag)

wxcli device-dynamic-settings (10 commands) changes phone settings by tag name across a whole model family — org-wide, per-location, or on one device — instead of editing devices one at a time. Endpoints live under /telephony/config/devices/dynamicSettings and /telephony/config/jobs/devices/dynamicDeviceSettings.

Use this when the request is "set X on all our 8845s" or "what settings can this model take?". Use device-settings (Step 6d) instead for members, line keys, and layout; use the device-platform skill for PhoneOS/RoomOS config keys on a named device.

Settings hierarchy: org (customer) --> location --> device. A lower scope overrides a higher one.

Discover what a model supports first:

# Which devices support dynamic settings (filter by type, e.g. MPP)
wxcli device-dynamic-settings list --type MPP --output json

# Which setting groups/tabs exist for a model
wxcli device-dynamic-settings list-settings-groups \
  --family-or-model-display-name "Cisco 8845" --include-settings-type ALL --output json

Read current settings at each scope:

# Org (customer) scope — NOTE: no --output flag on this command
wxcli device-dynamic-settings get-customer-device --family-or-model-display-name "Cisco 8845"

# Location scope (LOCATION_ID is a positional arg)
wxcli device-dynamic-settings get-location-device LOCATION_ID --family-or-model-display-name "Cisco 8845"

# Single device
wxcli device-dynamic-settings get-device-dynamic DEVICE_ID

NOTE: These three get-* commands are POST requests to .../actions/getSettings/invoke. They accept --json-body '{"tags":["..."]}' to filter to specific tags and have no --output flag — adding -o json fails.

Write settings:

# One device
wxcli device-dynamic-settings update DEVICE_ID \
  --json-body '{"tags":[{"tag":"...","action":"...","value":"..."}]}'

# Bulk across the org, or scoped to a location — returns a JOB_ID
wxcli device-dynamic-settings create --json-body '{
  "tags": [{"familyOrModelDisplayName": "Cisco 8845", "tag": "...", "action": "...", "value": "..."}],
  "locationId": "LOCATION_ID"
}'

WARNING: create is the bulk writer (org/location), not a "create a new thing" command. update targets a single device. The names are counterintuitive — read them carefully.

Track the bulk job:

wxcli device-dynamic-settings list-dynamic-device-settings --output json   # all jobs
wxcli device-dynamic-settings show JOB_ID --output json                    # job status
wxcli device-dynamic-settings list-errors JOB_ID --output json             # per-device failures

Bulk writes are asynchronous — a returned JOB_ID does not mean the fleet is updated. Poll show, then check list-errors for devices that failed.

6g. Workspace locations (legacy Workspaces API) -- NOT the same as wxcli locations

wxcli workspace-locations (10 commands) manages the legacy Workspaces-API location objects at /v1/workspaceLocations, plus their floors. wxcli locations manages Webex Calling locations at /v1/locations. Both groups expose the same 10 command names, so a wrong group silently targets the wrong object.

	wxcli workspace-locations	wxcli locations
Endpoint	/v1/workspaceLocations	/v1/locations
Object	Legacy Workspaces-API location (building)	Webex Calling location
create requires	--display-name, --address, --country-code, --latitude, --longitude	--name, --time-zone, --preferred-language, --announcement-language
list filters	--display-name, --address, --country-code, --city-name	--name, --id
Scope	spark-admin:workspace_locations_read / _write	spark-admin:locations_read / _write
Use for	Floors, lat/long geodata on legacy building records	Everything calling: users, numbers, devices, features

Rule of thumb: if the task involves calling — provisioning users, assigning numbers, creating devices or workspaces — you want wxcli locations. Only reach for workspace-locations to read/maintain legacy building records and floor lists.

# List legacy workspace locations (filters differ from wxcli locations)
wxcli workspace-locations list --country-code US --output json
wxcli workspace-locations list --city-name "San Francisco" --output json

# Show one, and its floors
wxcli workspace-locations show LOCATION_ID --output json
wxcli workspace-locations list-floors LOCATION_ID --output json

Deprecation note: docs/reference/devices-workspaces.md (Workspace Locations API section) marks this a legacy API and directs new work to wxcli locations. Prefer locations unless you specifically need floors or the legacy record.

---

Step 7: Verify

After execution, fetch details back and confirm:

# Verify device creation
wxcli devices show DEVICE_ID --output json

# Verify DECT network
wxcli dect-devices show LOCATION_ID DECT_NETWORK_ID --output json

# Verify workspace
wxcli workspaces show WORKSPACE_ID --output json

# Verify device members/lines
wxcli device-settings list DEVICE_ID --output json

# Verify device layout
wxcli device-settings list-layout DEVICE_ID --output json

# Verify workspace devices
wxcli device-settings list-devices-workspaces WORKSPACE_ID --output json

Step 8: Report results

Present the results:

DEVICE OPERATION COMPLETE
=========================
Operation: [type]
Device: [display_name]
ID: [device_id]
MAC: [mac_address]
Model: [model]
Assigned to: [person/workspace name] ([id])
Location: [location_name]
Status: [activation_state]

Next steps:
  - [Operation-specific next steps]
  - [e.g., "Enter activation code XXXX-XXXX on the phone"]
  - [e.g., "Configure line key template for standardized button layout"]
  - [e.g., "Add shared line appearances via device-settings update"]

---

Critical Rules

1. Always verify location exists before any device operation. Devices and workspaces are location-scoped.
2. Always show the deployment plan (Step 5) and wait for user confirmation before executing.
3. Always call apply-changes-for after settings changes. After updating device members, settings, or layout, call wxcli device-settings apply-changes-for DEVICE_ID to push config to the physical device. Without this, changes exist only in the cloud.
4. DECT dependency chain is strict. Network must exist before base stations. Base stations must exist before handsets. You cannot skip steps.
5. DECT serviceability password operations can reboot the entire network. Generating or toggling the password triggers a network-wide reboot. Schedule during maintenance windows.
6. 90-second cooldown on DECT handset changes. Adding or removing handsets within 90 seconds may leave base stations out of sync until rebooted.
7. Adding a DECT handset to a Standard license user disables Webex Calling on their mobile, tablet, desktop, and browser apps. Deleting the handset re-enables it. Use Professional licenses for users who need both.
8. Workspace location_id and supported_devices are immutable. Set correctly on creation; they cannot be changed afterward.
9. Deleting a workspace deletes all associated devices. Those devices must be reactivated (new activation code or MAC re-provision) to be reused.
10. Hot-desk-only workspaces cannot have phoneNumber, extension, calendar, or deviceHostedMeetings set. These cause errors if provided.
11. deviceModel is required for device settings GET/PUT. Omitting it from wxcli device-settings show-settings-devices returns an error.
12. Device IDs differ between API surfaces. The id from GET /devices (cloud CRUD) may differ from the telephony callingDeviceId. Use the correct ID for each CLI group.
13. No API for auto-generated DECT access codes. When defaultAccessCodeEnabled is false, per-handset codes are auto-generated but cannot be retrieved via API. Use Control Hub instead.
14. DECT handset Line 1 vs Line 2 member types. Line 1 supports only PEOPLE and PLACE. Line 2 also supports VIRTUAL_LINE. Virtual lines cannot be the primary (line 1) member.
15. Activation codes for phones require a model parameter. RoomOS collaboration devices do not require a model.
16. Background image limits. Max 100 images per org. Upload max 625 KB, .jpeg or .png only. Max 10 images per delete request.
17. DECT network create response uses dectNetworkId, not id. The CLI handles this, but if using raw HTTP, parse the correct key.
18. DECT is not supported for Webex for Government (FedRAMP).
19. Workspace call settings mirror person call settings. Use wxcli workspace-settings with the workspace ID. The sub-API is the same as person settings but workspace-scoped.
20. Maximum 5 devices per user (hardware + soft clients). POST /devices and POST /devices/activationCode return HTTP 400 "Phones cannot be added to this user" on the 6th device. Server-enforced, not configurable. Orphan devices from prior failed attempts count against the cap — delete stale devices before retrying. See docs/reference/devices-core.md Gotcha #12.
21. Model string format differs by phone family. Classic MPP phones use "DMS Cisco 8845" (with DMS prefix). 9800-series phones use "Cisco 9861" (no DMS prefix). Using the wrong format for device creation or line key templates will fail. Check wxcli device-settings list-supported-devices-dects --output json for exact model strings.
22. DECT display name character limits. Network displayName is max 11 characters. Handset customDisplayName is 1-16 characters. Exceeding limits returns 400.
23. DECT access code must be unique within the location. If two DECT networks at the same location share an access code, handsets may register with the wrong network.
24. workspace-locations is NOT locations. Both groups expose the same 10 command names but hit different endpoints (/v1/workspaceLocations vs /v1/locations) and different objects. Anything calling-related (users, numbers, devices, features) uses wxcli locations. workspace-locations is the legacy Workspaces-API building record — use it only for floors or legacy geodata. See Step 6g.
25. device-dynamic-settings get-* commands have no --output flag. get-customer-device, get-location-device, and get-device-dynamic are POST calls to .../actions/getSettings/invoke. Appending -o json fails. Filter with --json-body '{"tags":["..."]}'.
26. device-dynamic-settings create is the bulk writer, not a creator. create pushes tag changes org-wide or per-location and returns a JOB_ID; update writes a single device. Bulk writes are async — poll show JOB_ID and check list-errors JOB_ID before reporting success.

---

Registered CLI Groups (this skill only)

These are the exact group names registered in wxcli. Do not use any other group names:

CLI Group	Source File	Commands
wxcli devices	devices.py	list, create, show, update, delete, create-activation-code
wxcli device-settings	device_settings.py	46 commands (members, LKT, layout, settings, hoteling, validation, background images, jobs)
wxcli dect-devices	dect_devices.py	23 commands (networks, base stations, handsets, bulk, associations, serviceability)
wxcli workspaces	workspaces.py	list, create, show, update, delete, show-capabilities
wxcli workspace-settings	workspace_settings.py	60+ commands (call settings, monitoring, permissions, voicemail, recording)
wxcli device-configurations	device_configurations.py	show, update (PhoneOS/RoomOS config keys)
wxcli device-dynamic-settings	device_dynamic_settings.py	10 commands (supported devices, settings groups, org/location/device reads, per-device update, bulk job create, job status, job errors)
wxcli workspace-locations	workspace_locations.py	10 commands (legacy workspace locations + floors CRUD)
wxcli hot-desk	hot_desk.py	list, delete
wxcli hot-desking-portal	hot_desking_portal.py	show, update, show-guest, update-guest

NOT registered: user-call-settings (file exists but not wired into CLI). Use wxcli device-settings update-hoteling for person-level hoteling.

---

Scope Quick Reference

CLI Group	Read Scope	Write Scope
wxcli devices	spark-admin:devices_read	spark-admin:devices_write
wxcli device-settings	spark-admin:telephony_config_read	spark-admin:telephony_config_write
wxcli dect-devices	spark-admin:telephony_config_read	spark-admin:telephony_config_write
wxcli workspaces	spark-admin:workspaces_read	spark-admin:workspaces_write
wxcli workspace-settings	spark-admin:workspaces_read	spark-admin:workspaces_write
wxcli device-dynamic-settings	spark-admin:telephony_config_read	spark-admin:telephony_config_write
wxcli workspace-locations	spark-admin:workspace_locations_read	spark-admin:workspace_locations_write
wxcli hot-desk	(undocumented)	(undocumented)
wxcli hot-desking-portal	spark-admin:telephony_config_read	spark-admin:telephony_config_write

---

Context Compaction Recovery

If context compacts mid-execution, recover by:

1. Read the deployment plan from docs/plans/ to recover what was planned
2. Check what's already been created: run the relevant list / show commands
3. Resume from the first incomplete step