[WRITE] Grant desktop-pool access to AD user/group SID(s).

Get SIDs from search_ad_users. A bare call returns blast_radius (pool identity, which principals are already entitled and which are new) and grants nothing; confirm=True grants. Refused when the pool's current entitlements cannot be read. Show blast_radius to the user and wait for their decision. Do not set confirm=True on your own because the user asked for this earlier: they have not seen the blast radius yet. Audited.

[WRITE] Cancel a running pool task (e.g. an in-progress image push).

A bare call reads the task and returns blast_radius (task type, state, progress) and cancels nothing; confirm=True cancels. A task whose type or state cannot be read is refused. Work already applied is not rolled back. Show blast_radius to the user and wait for their decision. Do not set confirm=True on your own because the user asked for this earlier: they have not seen the blast radius yet. Audited.

[WRITE] Disconnect Horizon session(s) — state preserved, the user can reconnect.

Less disruptive than logoff. Identify by session_ids OR user. A bare call returns blast_radius (session ids, count, affected users) and changes nothing; confirm=True disconnects. A session whose user cannot be read is refused. Show blast_radius to the user and wait for their decision. Do not set confirm=True on your own because the user asked for this earlier: they have not seen the blast radius yet. Audited.

[READ] One desktop pool by id (teaching 404 on a wrong id).

Same projection as one list_desktop_pools row — id, name, type, enabled, provisioning_enabled, assignment — fetched with a single GET instead of listing every pool. Use it to re-check one pool after a write, or when you already hold an id.

[READ] Per-pool capacity: total / available / in-use / error machines and utilization %.

The "am I running out of desktops?" view, sorted by utilization. Drill in with list_vdi_machines --pool.

[READ] One-glance Horizon VDI health: session totals by state, problem machines, pool availability.

The first thing to call for "how is VDI right now?". Aggregates sessions, machines, and pools into a compact status. Drill into problems with list_vdi_machines --state or list_vdi_sessions.

[READ] One Horizon desktop machine by id (teaching 404 on a wrong id).

Same projection as one list_vdi_machines row — id, name, pool_id, state, assigned user, agent_version, base_image — fetched with a single GET instead of scanning the estate. Use it to re-check one machine after a write, or when you already hold an id.

[READ] Full detail for one Horizon session by id.

A wrong id returns a teaching error ("run list_vdi_sessions for current ids"), not a traceback. Use list_vdi_sessions to discover ids.

[READ] Session statistics: concurrency by state / protocol, current concurrent, busiest pools.

The reporting counterpart to list_vdi_sessions — aggregate numbers, not per-session rows.

[READ] Status of a pool's long task (image push / provisioning), or all tasks for the pool.

Horizon tasks are pool-scoped. Give task_id (from push_desktop_pool_image or a prior get_vdi_task_status) for one task; omit it to list all tasks for the pool.

[READ] List published application pools: id, name, farm, enabled, executable path. Paginated.

[READ] List Horizon desktop pools: id, name, type (AUTOMATED/MANUAL/RDS), enabled, assignment.

The verify pair for set_desktop_pool_enabled and push_desktop_pool_image. Paginated envelope.

[READ] List the AD users/groups entitled to a desktop pool (who can access it). Paginated.

A wrong pool id returns a teaching 404. Use list_desktop_pools for pool ids.

[READ] List Horizon RDS farms: id, name, type, enabled, RDS server count. Paginated.

[READ] List Horizon audit events (newest first), optionally filtered by severity. Paginated.

Each item: time, severity, type, module, user, machine, message. Use for "what went wrong recently".

[READ] List instant-clone base VMs and snapshots (the golden-image catalog for push_desktop_pool_image).

[READ] List Horizon desktop machines, filtered by pool id / state. Paginated.

Each item: id, name, pool_id, state (AVAILABLE/CONNECTED/AGENT_UNREACHABLE/PROVISIONING/ ERROR/MAINTENANCE/…), assigned user, agent_version, base_image. Verify pair for the machine write tools.

[READ] List Horizon VDI sessions, filtered by user / pool id / state. Paginated.

Returns a {items, returned, limit, total, truncated, hint} envelope; each item has id, user, type (DESKTOP/APPLICATION), state (CONNECTED/DISCONNECTED/PENDING), protocol (BLAST/PCOIP/RDP), pool_id, machine_id, start_time. This is the verify pair for logoff/disconnect — get a session id or confirm a user's sessions here first.

[WRITE] Force-logoff Horizon session(s) — kicks the user, triggers profile write-back.

Identify targets by explicit session_ids OR by user (all of that user's sessions). A bare call returns blast_radius — session ids, count and affected users — and logs off nothing; confirm=True logs off. A session whose user cannot be read is refused. Show blast_radius to the user and wait for their decision. Do not set confirm=True on your own because the user asked for this earlier: they have not seen the blast radius yet. Audited.

[WRITE] Apply the pending image to an instant-clone pool — RECREATES EVERY DESKTOP in it.

Highest blast radius in the family: the preview states affected-desktop and in-session counts before you confirm, plus blast_radius.occupancy — "determined" when those counts can be believed, "unknown" when sessions exist that cannot be attributed to any pool or farm. confirm=True schedules the apply. Show blast_radius to the user and wait for their decision. Do not set confirm=True on your own because the user asked for this earlier: they have not seen the blast radius yet. Audited.

[WRITE] Revoke desktop-pool access from AD user/group SID(s).

Get SIDs from list_entitlements. A bare call returns blast_radius (pool identity, which principals lose access and which were not entitled) and revokes nothing; confirm=True revokes. Refused when the pool's current entitlements cannot be read. Show blast_radius to the user and wait for their decision. Do not set confirm=True on your own because the user asked for this earlier: they have not seen the blast radius yet. Audited.

[WRITE] Remove machine(s) from their pool — for instant clones this DELETES the backing VM.

A bare call returns blast_radius (machine ids, names, states, assigned users) and removes nothing; confirm=True removes. A machine whose state cannot be read is refused. Show blast_radius to the user and wait for their decision. Do not set confirm=True on your own because the user asked for this earlier: they have not seen the blast radius yet. Audited.

[WRITE] Hard-reset desktop machine(s) — the user loses unsaved state.

A bare call returns blast_radius (machine ids, names, states, assigned users) and resets nothing; confirm=True resets. A machine whose state cannot be read is refused. Show blast_radius to the user and wait for their decision. Do not set confirm=True on your own because the user asked for this earlier: they have not seen the blast radius yet. For a graceful in-guest reboot use vmware-aiops (the vCenter VM). Audited.

[READ] Resolve AD users/groups by name to their SIDs — needed to entitle a pool (add_entitlement).

[WRITE] Send a message to Horizon session(s) — e.g. "save your work, maintenance in 10 min".

Low blast radius (informational only, no session disruption), so no confirm gate. Identify by session_ids OR user. Audited.

[WRITE] Enable or disable a desktop pool — disabling stops NEW sessions (existing keep running).

Idempotent (matching state returns a noop). A bare call returns blast_radius (pool identity, current and new enabled state) and changes nothing; confirm=True applies. A pool whose current enabled state cannot be read is refused. Show blast_radius to the user and wait for their decision. Do not set confirm=True on your own because the user asked for this earlier: they have not seen the blast radius yet. Audited.

[WRITE] Enter (enabled=True) or exit (False) maintenance mode for machine(s).

Maintenance drains the machine (no new sessions). A bare call returns blast_radius (machine ids, states, assigned users) and changes nothing; confirm=True applies. A machine whose state cannot be read is refused. Show blast_radius to the user and wait for their decision. Do not set confirm=True on your own because the user asked for this earlier: they have not seen the blast radius yet. Audited.