[WRITE] Acknowledge a triggered vCenter alarm — marks it as seen WITHOUT clearing it.

This only marks the alarm; it does not clear it. The alarm stays in the active list with acknowledged=true until its condition clears or it is reset. To remove it entirely after fixing the root cause use reset_vcenter_alarm instead. Get exact entity_name and alarm_name from list_vcenter_alarms first; an unknown pair returns a not-found error.

Returns: Dict: entity_name, alarm_name, action ("acknowledged"), acknowledged (true).

[WRITE] Add a static-IP VMkernel adapter on a DVS portgroup - preview/confirm gated.

Deliberately minimal shape for throwaway test vmks on L2-only segments (e.g. a TEP VLAN): static IPv4, NO gateway, NO services enabled. The DVS port allocation is handled internally - pass the distributed portgroup name. confirm=False validates (host + portgroup exist, IP/netmask/MTU legal, IP not already on the host) and returns the exact spec without writing; confirm=True creates and returns the assigned device name. Verify with list_host_vmks; remove with remove_host_vmk. Audited.

Returns: Preview dict (action="preview") or result dict (action="created", device=e.g. "vmk2"). Errors return a dict with "error" + hint.

[WRITE] Mount a datastore ISO into a VM's virtual CD-ROM drive.

Reconfigures the existing CD-ROM (replacing any mounted ISO) or adds one on the VM's IDE controller; fails with a clear message if the VM has no IDE controller. Works whether the VM is powered on or off. Find ISO paths first with browse_datastore using pattern "*.iso". Returns a status string confirming attachment, or a VM-not-found / no-IDE-controller error.

[WRITE] Batch clone multiple VMs from a source VM (gold image).

Each clone: full copy → optional reconfigure → optional snapshot → optional power on. Returns one dict per VM with its status. Clones run sequentially, so a long vm_names list may take a while — prefer batch_linked_clone_vms for disposable test copies.

[WRITE] Deploy multiple VMs in one call from a declarative YAML spec file.

Use for fleet provisioning (several VMs, shared defaults); for a single VM prefer deploy_vm_from_template, vm_clone, deploy_vm_from_ova, or deploy_linked_clone. The channel is chosen by spec keys: "source" (full clone), "template", "linked_clone: {source, snapshot}", per-VM "ova", else empty-VM creation (optionally "iso"). A "defaults" block sets cpu/memory_mb/disk_gb/network/ datastore/snapshot/power_on, overridable per VM. VMs deploy sequentially and one VM's failure does not stop the rest.

Returns: One dict per VM: name, status ("ok" or "error"), and messages with per-step results.

[WRITE] Batch create linked clones from a VM snapshot (fastest batch provisioning).

Clones share the source disk via copy-on-write, so the source must stay intact. Returns one dict per clone. Prefer batch_clone_vms for independent copies.

[READ] Browse files in a vSphere datastore directory.

Use this to find OVA/ISO/VMDK paths before calling deploy_vm_from_ova or attach_iso_to_vm; for an estate-wide image sweep use scan_datastore_images.

Returns the list envelope: 'items' is one row per file, and 'returned'/'total'/'truncated' state completeness. Every match in the searched folders is returned, so truncated is always false.

[WRITE] Move an ESXi host that vCenter already manages into a cluster.

The host must already be in vCenter inventory (standalone or in another cluster) — this does NOT register brand-new hosts and takes no host credentials; use the vCenter UI for first-time registration. Idempotent: a host already in the cluster returns success without change. Maintenance mode is not required to join (it IS required by cluster_remove_host). Check membership first with cluster_info. Returns a status string: moved, already-in-cluster, or a not-found error.

[WRITE] Reconfigure cluster HA/DRS settings.

Returns a status string naming what changed. Pass only the fields to change; None leaves a setting untouched — then verify with cluster_info. drs_behavior applies only when DRS is enabled.

[WRITE] Create a new empty cluster in a datacenter, optionally enabling HA and DRS.

Fails with a clear error (no partial state) if the name already exists or drs_behavior is invalid. Then add hosts with cluster_add_host, change HA/DRS later with cluster_configure, and verify with cluster_info. Returns a status string naming the features enabled.

[WRITE] Delete an empty cluster (no hosts must remain).

Without confirm=True this only previews: it returns blast_radius (cluster name and id, host/VM/datastore counts and names, blockers) and deletes nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet.

Refused: a cluster that still has hosts or VMs (evacuate members with cluster_remove_host first), or one whose members could not be read. Check cluster_info first. Returns a dict (action, blast_radius).

[READ] One-glance health rollup for every cluster — "is anything on fire?".

Aggregates hosts, VM power state, live CPU/memory pressure, triggered alarms and datastores thin-provisioned past 100% of capacity per cluster, assigns each a status ("ok"/"warn"/"critical"), and flattens the anomalies into a ranked top_issues focus list — the fast triage view for "what's wrong right now?". Read-only (delegates to the vmware-monitor library). Use it FIRST for a cross-cluster glance, then drill in with vm_investigation_bundle or host_investigation_bundle.

Returns {totals, top_issues, issues_total, clusters, snapshot, customization_hint}. Lead with top_issues (worst first, each with a drill-down hint), clusters as context, customization_hint last. Point-in-time — no trending.

[READ] Get detailed cluster information: member hosts, HA/DRS config, resource capacity.

Read-only, no side effects. Use before cluster_add_host / cluster_remove_host (shows membership and per-host maintenance mode) and to verify cluster_configure changes.

Returns: Dict with name, host_count, hosts (each: name, connection_state, power_state, maintenance_mode), ha_enabled, ha_admission_control, drs_enabled, drs_behavior, total/effective CPU (MHz) and memory (GB). Errors return a dict with "error" + hint.

[WRITE] Remove a host from a cluster (host must be in maintenance mode).

Without confirm=True this only previews: it returns blast_radius (host name and id, maintenance mode, VM count, powered-on VM count, blockers) and moves nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet.

Refused: a host not in maintenance mode, a host with powered-on VMs, and a host whose state could not be read. Run cluster_info first for the exact member host names. The host is not deleted — it stays in vCenter inventory standalone; use cluster_add_host to move it back. Returns a dict.

[WRITE] Convert a powered-off VM to a vSphere template.

Returns a status string. Use this to freeze a golden image: afterwards the VM cannot be powered on and serves only as a clone source for deploy_vm_from_template.

[WRITE] Create a VM-VM DRS rule (affinity or anti-affinity) - preview/confirm gated.

rule_type "affinity" keeps the listed VMs together; "antiAffinity" keeps them apart (e.g. redundant appliance pairs on separate hosts). Requires >=2 distinct VMs, all members of the cluster. VM-Host rules hang off cluster VM/host groups and are not created here. Verify with list_drs_rules. Audited.

Returns: Preview dict (action="preview", would_create) or result dict (action="created", created incl. the assigned key). Errors return a dict with "error" + hint.

[WRITE] Create a VLAN-tagged portgroup on a dvSwitch - preview/confirm gated.

confirm=False (default) validates everything (switch exists, name free, binding and VLAN legal) and returns the exact spec that WOULD be created without writing anything. confirm=True creates the portgroup and waits for the task. Verify afterwards with list_dvs_portgroups. Audited.

binding="ephemeral" creates a portgroup with no pre-created port pool, attachable from the ESXi host client even when vCenter is down - use for a self-hosted VCSA's own management portgroup. num_ports is ignored for ephemeral. lateBinding is deprecated by vSphere and not offered.

Returns: Preview dict (action="preview", would_create) or result dict (action="created", created). Errors return a dict with "error" + hint.

[READ] "What needs attention now?" across EVERY configured vCenter — one list.

Runs cluster_health_summary against every configured target and returns one globally ranked top_issues list (worst first, each tagged with its vcenter) plus a per-target rollup — "where do I look first, anywhere in the estate?". Degrades gracefully: an unreachable target is listed under unreachable and the rest still aggregate. Delegates to the vmware-monitor library (read-only). Lead with top_issues, then drill in with vm_investigation_bundle. Point-in-time.

[READ] "What is happening around this datastore?" — one correlated drill-down.

Correlates a datastore's capacity/free space/accessibility, the hosts that mount it, a rollup of the VMs it backs, alarms across datastore/host, and a merged event timeline. Delegates to the vmware-monitor library (read-only); do not dump the result raw. (Per-datastore latency is a separate perf report.)

Use this AFTER cluster_health_summary flags storage pressure. Point-in-time.

[WRITE] Delete a VM-VM DRS rule - confirm-gated, guarded.

REFUSES non-VM-VM rules: VM-Host rules can carry licensing/compliance placement constraints (must-run-on licensed hosts) and hang off cluster groups - manage those in the vSphere UI. The preview and result both record the full rule definition so a mistaken delete can be recreated from the audit trail. Audited.

Returns: Preview dict (action="preview", would_delete) or result dict (action="deleted", deleted). Errors return a dict with "error" + hint.

[WRITE] Create a linked clone from a VM snapshot — near-instant, minimal disk usage.

The clone writes to a copy-on-write delta over the source's base disk, so it depends on the source staying intact. Fastest provisioning for test/dev fleets; use vm_clone for fully independent copies. Requires the named snapshot — run vm_list_snapshots first. Returns a status string with the new clone name.

[WRITE] Create a new VM by importing a local .ova file (OVF parse + VMDK upload).

Use for local OVA files; for vSphere templates use deploy_vm_from_template, to copy an existing VM vm_clone. Returns a status string naming the new VM. Upload time scales with OVA size; fails before creating anything if the datastore is not found.

[WRITE] Deploy a new VM by cloning from a vSphere template.

Returns a status string. Use for VMs marked as templates; for a running source VM use vm_clone. Requires an existing template — convert_vm_to_template makes one.

[READ] "What is happening around this ESXi host?" — one correlated drill-down.

Correlates a host's state (connection, CPU/memory, ESXi version, uptime), its cluster context, a rollup of the VMs it runs, the datastores it mounts, alarms across host/cluster/datastore, live performance, and a merged event timeline. Delegates to the vmware-monitor library (read-only); do not dump the result raw.

Use this AFTER cluster_health_summary flags a host. Point-in-time.

[READ] List a cluster's DRS rules: VM-VM affinity/anti-affinity and VM-Host.

Per rule: key, name, type (affinity / antiAffinity / vmHost), enabled, mandatory, and the member VM names (VM-VM) or group names (VM-Host). The verify pair for create/delete/set_drs_rule_enabled.

Returns: Dict with cluster, count, and rules sorted by name. Errors return a dict with "error" + hint.

[READ] List distributed virtual portgroups, optionally scoped to one dvSwitch.

Per portgroup: name, parent dvSwitch, binding type (earlyBinding / ephemeral), VLAN setting (id, trunk ranges, or pvlan), configured port count, and whether it is the switch's uplink portgroup. Use to verify create_dvs_portgroup results or to survey network config before changes.

Returns: The family list envelope {items, returned, limit, total, truncated, hint}; each item is one portgroup. portgroups is kept as a deprecated alias for items. Errors return a dict with "error" + hint.

[READ] List VMkernel adapters, optionally scoped to one ESXi host.

Per vmk: device, IP/netmask/dhcp, MTU, MAC, portgroup (standard or DVS), netstack, and which host services it is selected for (management, vmotion, vsan, ...). The verify pair for add_host_vmk/remove_host_vmk.

Gotcha - this list is not automatically a complete estate inventory. vCenter answers property reads for a host it has lost contact with out of its own cache, so hosts it never reached appear here as rows with reachable: false, device: null and a note naming the connectionState, rather than being dropped. Check hosts_unreachable (and the unreachable_note present only when it is non-zero) before reporting the result as the full picture, and do not read a null field on such a row as a measurement - it means nobody looked. Adapters shown for an unreachable host are vCenter's last cached view.

Returns: The family list envelope {items, returned, limit, total, truncated, hint} plus hosts_unreachable (int) and, when that is non-zero, unreachable_note (str). Each item is one VMkernel adapter, or one unread host when reachable is false; services is null when a host's service map could not be read. truncated stays a paging fact - an incomplete estate is reported by hosts_unreachable, not by it. vmks is kept as a deprecated alias for items. Errors return "error" + hint.

[READ] List active/triggered alarms across the vCenter inventory.

Start here for alarm work: it supplies the exact entity_name/alarm_name pair that acknowledge_vcenter_alarm and reset_vcenter_alarm require.

Returns the list envelope: 'items' holds severity (critical/warning/info), entity name and type, alarm name, acknowledged flag, and trigger time; 'returned'/'limit'/'total'/'truncated'/'hint' state completeness, so a limited page is never mistaken for the whole picture. 'total' is the real active-alarm count — every alarm is collected before the limit is applied.

[WRITE] Remove a VMkernel adapter - confirm-gated, guarded, fail-closed.

REFUSES (unless force_unprotected=True) when the vmk is selected for any host service (management/vmotion/vsan/...), lives on a non-default netstack (NSX TEPs on vxlan, dedicated vmotion/provisioning stacks - never visible in the service map), carries a default gateway route, or when any of that CANNOT be verified - unverifiable is treated as unsafe, never as clear. Test vmks created by add_host_vmk trip none of these and remove cleanly without force.

ABSOLUTE, no override: the host's only management-enabled vmk is never removable - this call rides the interface it would delete.

force_unprotected=True (together with confirm=True) overrides the non-absolute protections for deliberate teardown; the override and every bypassed protection are recorded in the result (and the audit trail).

Returns: Preview dict (action="preview") or result dict (action="removed", plus forced/protections_bypassed when overridden). Errors return a dict with "error" + hint.

[WRITE] Clear triggered vCenter alarms back to normal state.

Use this after resolving the underlying issue; to merely mark an alarm seen use acknowledge_vcenter_alarm instead. Get entity_name and alarm_name from list_vcenter_alarms first.

Gotcha: vSphere has no per-alarm clear — this clears ALL triggered alarms matching the named alarm's entity type (host/VM/all) and current status (red/yellow), so confirm the blast radius with the user first. Returns a dict whose 'scope' field states exactly what was cleared.

[READ] Scan all accessible datastores for deployable images (OVA/ISO/OVF/VMDK).

Returns the images found and refreshes the cache at ~/.vmware-knight/image_registry.json. Use this when you do not know which datastore holds an image; prefer browse_datastore once you do, because this walks every datastore and may take minutes on a large estate.

Returns: The family list envelope {items, returned, limit, total, truncated, hint} plus last_scan; each item is one image. images is kept as a deprecated alias for items.

[WRITE] Enable or disable an existing DRS rule - preview/confirm gated.

The day-2 toggle: anti-affinity rules often must be disabled while a cluster is temporarily too small to satisfy them, then re-enabled when hosts return. Idempotent - matching state returns a noop, no write. Names are matched exactly; ambiguous names refuse. Audited.

Returns: Preview dict (action="preview"), noop dict (action="noop"), or result dict (action="set", rule_now). Errors return "error" + hint.

[WRITE] Enable/disable a host service on an existing vmk - preview/confirm gated.

Completes the add_host_vmk story: adapters are created serviceless by design, then tagged here (e.g. enable "vmotion" on a new vMotion vmk). Idempotent - re-applying the current state returns a no-write noop. Verify with list_host_vmks (the services field). Audited.

Valid services are the vSphere nicType names: management, vmotion, vsan, vSphereProvisioning, faultToleranceLogging, vSphereReplication, vSphereReplicationNFC, vSphereBackupNFC, ptp, and the nvme/vsan variants. Note "vSphereProvisioning", not "provisioning".

FAIL CLOSED: refuses both directions when the host's service map cannot be read. ABSOLUTE, no override: disabling management on the host's only management-enabled vmk - the call rides the interface it would untag.

Returns: Preview dict (action="preview"), noop dict (action="noop") when the state already matches, or result dict (action="set", services_now). Errors return a dict with "error" + hint.

[WRITE] Execute a previously created plan step by step.

Without confirm=True this only previews: it returns blast_radius listing every step (index, action, target object), the count and indices of the destructive ones (delete, power off, revert, guest commands...), and blockers — and runs nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet.

Each step is shown with its full parameters (passwords redacted). Each destructive step is measured as its own tool would measure it (vm_delete, vm_power_off, vm_revert_snapshot, vm_guest_exec, cluster_delete ...), and that tool's blockers refuse the plan. A step on something an earlier step creates or changes is marked check "deferred": it is measured immediately before it runs, and the plan stops there if it fails.

Refused: a target other than the one the plan was created against (no target is a target of its own), a step its tool would refuse, anything it could not read, a delete_vm step without its acknowledge_blast_radius (from a vm_delete preview), and any iscsi_* or storage_rescan step — those are gated in vmware-storage; run storage_iscsi_* / storage_rescan there.

With confirm=True steps run sequentially. On failure: stops immediately, keeps the plan file with per-step results, and returns rollback_available. On success: deletes the plan file. If a step fails and rollback_available is true, ask the user whether to rollback, then call vm_rollback_plan.

[WRITE] Cancel an existing TTL for a VM (prevents auto-deletion).

Returns a status string. Use vm_list_ttl first for the exact vm_name. This only removes the schedule and never touches the VM itself.

[WRITE] Revert a VM to its baseline snapshot (Clean Slate).

Without confirm=True this only previews: it returns blast_radius (VM identity, power state and whether it is powered off first, the snapshot and when it was taken, snapshot count, blockers) and changes nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet.

With confirm=True: powers off the VM first if it is running, then reverts to the named snapshot. Use this to reset a lab/dev VM to a clean starting state after a task completes. Irreversible — everything written since the snapshot is lost. Refused: no snapshot of that name, more than one, or a VM whose state cannot be read. Returns a dict (action, blast_radius).

[WRITE] Clone a VM. Without to_host/to_datastore the clone lands on the source's host+datastore.

Returns a status string naming the clone. Full independent copy — slow and full disk cost; prefer deploy_linked_clone for near-instant test copies and batch_clone_vms for many at once. Cloning a running VM may capture a crash-consistent disk.

[WRITE] Create a new empty VM with the given hardware sizing.

Creates a powered-off VM with one disk and one NIC. To populate it, attach an ISO (attach_iso_to_vm) and power it on, or use deploy_vm_from_ova or vm_clone for a ready-to-run guest. Fails before creating anything if the datastore is not found. Returns a status string with the new VM name.

[WRITE] Create an execution plan for multi-step VM operations.

Use for 2+ steps or 2+ VMs. Validates actions, checks the targets exist in vSphere, and generates a plan with rollback info per step.

Each operation is a dict with "action" key plus action-specific params. Allowed actions: power_on, power_off, reset, suspend, create_vm, delete_vm, reconfigure, create_snapshot, delete_snapshot, revert_snapshot, clone, migrate, deploy_ova, deploy_template, linked_clone, attach_iso, convert_to_template.

Returns plan dict with plan_id, steps, summary (vms_affected, irreversible_steps, rollback_available). Show to user for confirmation before calling vm_apply_plan.

[WRITE] Create a snapshot of a VM.

Returns a status string. Use this before a risky change so vm_revert_snapshot can undo it, then reclaim the space with vm_delete_snapshot — snapshots left for days grow delta disks and must not be treated as backups.

[WRITE] Delete a VM and its disks and snapshots (irreversible).

Without confirm=True this only previews: it returns blast_radius (identity, host, disks, total size, snapshot count, blockers) and destroys nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user said "delete" earlier: they have not seen what it destroys yet.

To delete, call again with confirm=True and acknowledge_blast_radius set to the preview's acknowledge_with object, unchanged. The VM is re-measured first; if it changed (another snapshot, a different VM under the same name), nothing is deleted and you must preview again.

Refused outright: a powered-on or suspended VM (power it off with vm_power_off first), a VM whose disks or identity cannot be read, and a name that matches more than one VM. Use vm_set_ttl instead when the VM should only expire later.

[WRITE] Permanently delete a named snapshot, consolidating its delta disk into the parent.

Without confirm=True this only previews: it returns blast_radius (VM and instance UUID, the snapshot's name, id and creation time, remove_children, how many child snapshots sit below it and how many snapshots would be removed) and deletes nothing. Show it to the user and get their decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet.

Frees disk space and does NOT change the VM's current state (unlike vm_revert_snapshot). Works while the VM is powered on. Refused: a snapshot name that is not found, a name that matches more than one snapshot on the VM (vSphere allows duplicates; rename one first), and a snapshot tree that cannot be read. Run vm_list_snapshots first for exact names.

Consolidation is slow for old/large deltas (often minutes). By default (wait=False) this returns a task id immediately so it does not block your context — poll it with vm_task_status. Set wait=True only for small snapshots (blocks up to 30 min).

Returns: Dict with action (preview, snapshot_delete_started, snapshot_deleted), blast_radius, and result (carries the task id to poll via vm_task_status).

[WRITE] Download a file from a VM and write it to a local path.

Reads from the guest, writes the local filesystem — the write is why this is not a read tool. Returns a status string. Requires VMware Tools running in the guest OS. Use vm_guest_upload for the reverse direction; to capture command output use vm_guest_exec_output instead — it redirects and downloads for you.

Refuses a destination that already exists unless overwrite=True, and never writes through a symlink or over a directory. Pick a path that does not exist yet rather than passing overwrite=True by default.

[WRITE] Execute a command inside a VM via VMware Tools.

Requires VMware Tools running in the guest OS. Returns exit_code, stdout, stderr, timed_out, and blast_radius.

Without confirm=True this only previews: blast_radius names the VM (name, instance UUID), the guest account, the exact command, arguments and working directory, VMware Tools status and any blockers; nothing runs. Show it to the user. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Refused outright: VM not powered on, VMware Tools not running, an identity or status that cannot be read, or a name that matches more than one VM.

Note: the Guest Ops API does not capture stdout/stderr directly, so use this only for fire-and-forget commands — prefer vm_guest_exec_output whenever you need the output.

[WRITE] Execute a shell command inside a VM and capture stdout + stderr.

Automatically detects guest OS (Linux/Windows) and selects the correct shell. Output is captured by redirecting to a temp file, downloading it, then cleaning up — no manual redirection needed. Prefer this over vm_guest_exec whenever you need the output. Requires VMware Tools running and a writable temp directory in the guest.

Returns exit_code, stdout, stderr, timed_out, os_family, and blast_radius.

Without confirm=True this only previews: blast_radius names the VM (name, instance UUID), the guest account, the exact command and the shell it runs through, VMware Tools status and any blockers; nothing runs. Show it to the user. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Refused outright: VM not powered on, VMware Tools not running, an unreadable identity or status, or a name that matches more than one VM.

[WRITE] Provision a VM by running an ordered sequence of guest operations.

Prefer this over repeated vm_guest_exec / vm_guest_upload calls when the steps form one provisioning run. Steps stop on the first failure, so a partial run leaves the guest half-configured. Requires VMware Tools running in the guest.

Without confirm=True this only previews: blast_radius names the VM (name, instance UUID), the guest account and every step it would run, in order, with counts per type, local file sizes and any blockers; nothing runs. Show it to the user. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Refused outright: VM not powered on, VMware Tools not running, an empty step list, a step with an unknown type or a missing key, an upload whose local file is missing or unreadable, a service step on a Windows guest, an unreadable identity or status, or a name that matches more than one VM.

Step types:

• exec: {"type": "exec", "command": "apt-get install -y nginx"}

• upload: {"type": "upload", "local_path": "...", "guest_path": "..."}

• service: {"type": "service", "name": "nginx", "action": "start"}

Returns: dict with success, completed_steps, total_steps, results, error, and blast_radius.

[WRITE] Upload a file from local machine to a VM via VMware Tools.

Returns a dict with action, message and blast_radius (a status string before the confirmation gate). Requires VMware Tools running in the guest OS. An existing file at guest_path is replaced. Use vm_guest_download for the reverse direction, and vm_guest_provision instead when uploads and commands belong to one ordered provisioning run.

Without confirm=True this only previews: blast_radius names the VM (name, instance UUID), the guest account, the local path and size, the guest path, VMware Tools status and any blockers; nothing is transferred. Show it to the user. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Refused outright: VM not powered on, VMware Tools not running, a local file that is missing or unreadable, an unreadable identity or status, or a name that matches more than one VM.

[READ] "What is happening around this VM?" — one correlated drill-down.

Correlates everything around one VM so you don't stitch it together yourself: the VM's state, its host, cluster context, backing datastores, snapshots, triggered alarms, live performance, and a merged event timeline across VM, host, cluster and datastores (newest first). Batched, cheap even on large fleets. Delegates to the vmware-monitor library (read-only). Explain the result in operational language; do not dump it raw.

Use this AFTER cluster_health_summary points at a problem VM. Point-in-time.

[READ] DF-bit-capable ping sourced from a host vmk - MTU path validation.

Runs esxcli network diag ping on the ESXi host through the vSphere API (no host SSH). df=True sets Don't-Fragment so an oversized packet FAILS instead of fragmenting - that failure is the diagnostic:

• df=True size=1572 proves a >=1600 MTU path (overlay/TEP floor)

• df=True size=8972 proves full jumbo (9000 minus 28 bytes overhead) A too-big result reports 'Message too long' in the fault field rather than erroring - read success + fault together.

Returns: Dict with request, success, and summary (transmitted/received/loss/ rtt) or fault (the esxcli failure text). Errors return "error" + hint.

[READ] List all pending/failed plans.

Use this first to find a plan_id for vm_apply_plan or vm_rollback_plan. Returns the list envelope: 'items' holds plan summaries (plan_id, created_at, status, steps count, VMs affected), and 'returned'/'total'/ 'truncated' state whether the listing is complete. Every plan file is read, so truncated is always false. Listing never deletes: stale plans (>24h) are swept by vm_create_plan, not by this tool.

[READ] List the full snapshot tree of a VM, including nested child snapshots.

Read-only, no side effects. Call this before vm_revert_snapshot, vm_delete_snapshot, or deploy_linked_clone to get exact snapshot names. 'items' is empty when the VM has no snapshots.

Returns: The list envelope. 'items' is one dict per snapshot: name, description, created, state (power state at snapshot time), level (0 = root). The whole tree is walked, so 'total' is the real count and 'truncated' is always false.

[READ] List all VMs with TTLs registered, including expiry time and status.

Use this first to find the exact vm_name for vm_cancel_ttl. Returns the list envelope: 'items' holds TTL entries with remaining_minutes and expired flag, and 'returned'/'total'/'truncated' state whether the listing is complete. The whole TTL store is read, so truncated is always false.

[WRITE] Migrate (vMotion) a VM to another host, optionally with storage vMotion.

Without confirm=True this only previews: it returns blast_radius (VM and instance UUID, source host and datastores, target host with its connection and maintenance state, target datastore, and live vMotion vs cold migration) and moves nothing. Show it to the user and get their decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet.

Refused: a target host that is not found, not connected, in maintenance mode or outside a cluster; a target datastore that is not found; a target host that does not mount the VM's datastores when to_datastore is omitted (vCenter rejects cross-host vMotion without shared storage — pass to_datastore); and anything above that cannot be read. The VM's current host with no to_datastore returns action "noop". Run cluster_info first for host names.

Returns: Dict with action (preview, noop, migrated), blast_radius, and result.

[WRITE] Power off a VM — graceful guest shutdown by default, hard power-off with force=True.

Without confirm=True this only previews: it returns blast_radius (VM name and instance UUID, host, power state, VMware Tools status, and whether this is a guest shutdown or a hard power-off) and changes nothing. Show it to the user and get their decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet.

Graceful mode calls VMware Tools guest shutdown and waits up to 120s; if it does not finish, action is "still_running". Refused: a graceful shutdown when Tools is not running or the VM is suspended (preview force=True instead), and a VM whose identity or power state cannot be read. An already-off VM returns action "noop". Use vm_power_on to start a VM; vm_delete requires it off first.

Returns: Dict with action (preview, noop, powered_off, still_running), blast_radius, and the executor's message under result.

[WRITE] Power on a virtual machine.

Returns a status string; an already-on VM is a no-op. Reverse with vm_power_off. Call this first when a VM is off: guest tools such as vm_guest_exec only work once VMware Tools has finished booting.

[WRITE] Change a VM's vCPU count and/or memory.

Pass only the fields you want to change; omitted fields are left untouched. Hot-add of CPU/memory requires it to be enabled on the VM and a running guest; otherwise power the VM off first (vm_power_off).

Returns: Status string describing the applied change, or a VM-not-found error.

[WRITE] Revert a VM to a named snapshot (loses changes since snapshot).

Without confirm=True this only previews: it returns blast_radius (VM and instance UUID, the snapshot's name, id and creation time, total snapshot count, current power state and the power state after the revert) and changes nothing. Show it to the user and get their decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet.

Irreversible — everything written since the snapshot is lost. Refused: a snapshot name that is not found, a name that matches more than one snapshot on the VM (vSphere allows duplicates; rename one first), and a VM whose snapshot tree, identity or power state cannot be read. Run vm_list_snapshots first for exact names. To reclaim space without changing state use vm_delete_snapshot.

Returns: Dict with action (preview, reverted), blast_radius, and result.

[WRITE] Rollback executed steps of a failed plan in reverse order.

Without confirm=True this only previews: it returns blast_radius listing the rollback steps that would run (in order, with the VMs a rollback deletes) and those skipped as irreversible — and runs nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet.

Only call this after vm_apply_plan returns status='failed'; check vm_list_plans first for the plan_id. Irreversible steps (delete_vm, revert_snapshot, etc.) are skipped with a warning. Each destructive rollback step (power off, delete snapshot, cluster delete, host removal) is measured as its own tool measures it, in the preview and again just before it runs; a refused check stops the rollback there and the plan stays 'failed'. Refused on a target other than the one the plan was created against.

[WRITE] Set a Time-To-Live (TTL) for a VM. The daemon auto-deletes it when expired.

Without confirm=True this only previews: it returns blast_radius — the VM that will be deleted (identity, host, disks, total size, snapshot count), when (expires_at), and any TTL it replaces — and schedules nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Refused when the VM's identity or disks cannot be read.

Use this for short-lived lab VMs so cleanup is not forgotten; cancel with vm_cancel_ttl and review pending expiries with vm_list_ttl. The scheduler daemon must be running (vmware-knight daemon start) or nothing is ever deleted; it powers a running VM off first. TTLs persist in ~/.vmware-knight/ttl.json. Returns a dict (action, blast_radius).

[READ] Poll a long-running vSphere task by its id (from an async vm_delete_snapshot).

Use after vm_delete_snapshot returns a task id, instead of re-running the delete. Returns state (queued/running/success/error/gone), progress percent, and the entity name. 'gone' means vCenter already garbage-collected a completed task — re-list the resource to confirm the final state. A failed task reports its fault under 'task_error'; a top-level 'error' key would mean this poll itself failed.

Returns: Dict with task_id, state, progress_pct, operation, entity, and task_error/note when relevant.