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

The alarm stays in the active list with acknowledged=true until its condition clears or it is reset. To remove the alarm entirely after fixing the root cause, use reset_vcenter_alarm instead. Get exact entity_name and alarm_name values from list_vcenter_alarms first; an unknown pair returns a not-found error. Audited to ~/.vmware/audit.db.

Args: entity_name: Name of the VM, ESXi host, or cluster the alarm fired on (from list_vcenter_alarms output). alarm_name: Exact alarm definition name, e.g. "Virtual machine CPU usage". target: vCenter target name from config.yaml; omit to use the default target.

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

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

Reconfigures the existing CD-ROM (replacing any currently mounted ISO) or adds a new CD-ROM on the VM's IDE controller if none exists; fails with a clear message if the VM has no IDE controller. Works whether the VM is powered on or off — the device is set connected and start-connected. Find ISO files first with browse_datastore using pattern "*.iso". Audited to ~/.vmware/audit.db.

Args: vm_name: Exact VM name as shown in vCenter inventory. iso_ds_path: Full datastore path in bracket format, e.g. "[datastore1] iso/ubuntu-22.04.iso" (datastore name in brackets, then the path relative to the datastore root). target: vCenter/ESXi target name from config.yaml; omit to use the default target.

Returns: 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.

Args: source_vm_name: Source VM to clone from. vm_names: List of names for the new VMs. cpu: Override CPU count for all clones (optional). memory_mb: Override memory for all clones (optional). snapshot_name: Create a baseline snapshot on each clone (optional). power_on: Power on each clone after creation. target: Optional vCenter/ESXi target name from config.

[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 provisioning channel is chosen by spec keys: top-level "source" (full clone), "template", "linked_clone: {source, snapshot}", per-VM "ova", else empty-VM creation (optionally with "iso"). A "defaults" block sets cpu/memory_mb/disk_gb/network/ datastore/snapshot/power_on, overridable per VM. VMs deploy sequentially; one VM's failure is recorded and the rest continue. Audited to ~/.vmware/audit.db.

Args: spec_path: Local filesystem path to the deploy.yaml specification file. target: vCenter/ESXi target name from config.yaml; omit to use the default target.

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).

Each clone shares the source disk via copy-on-write.

Args: source_vm_name: Source VM to clone from. snapshot_name: Snapshot to use as clone base. vm_names: List of names for the new linked clones. cpu: Override CPU count (optional). memory_mb: Override memory (optional). power_on: Power on each clone. baseline_snapshot: Create a new snapshot on each clone (optional). target: Optional vCenter/ESXi target name from config.

[READ] Browse files in a vSphere datastore directory.

Use this to discover OVA, ISO, VMDK, and other files on datastores before deploying VMs.

Args: datastore_name: Name of the datastore to browse. path: Subdirectory path (empty string for root). pattern: Glob pattern to filter files (e.g. ".ova", ".iso", "*"). target: Optional vCenter/ESXi target name from config.

[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 tool does NOT register brand-new hosts and takes no host credentials; use the vCenter UI for first-time host 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 with cluster_info. Audited to ~/.vmware/audit.db.

Args: cluster_name: Existing destination cluster name (create with cluster_create). host_name: Host name exactly as shown in vCenter inventory, typically the FQDN, e.g. "esxi-01.lab.local". target: vCenter target name from config.yaml; omit to use the default target.

Returns: Status string: moved, already-in-cluster, or host/cluster-not-found error.

[WRITE] Reconfigure cluster HA/DRS settings.

Args: name: Cluster name. ha: Enable (True) or disable (False) HA, or None to leave unchanged. drs: Enable (True) or disable (False) DRS, or None to leave unchanged. drs_behavior: DRS behavior: "fullyAutomated", "partiallyAutomated", or "manual". target: Optional vCenter target name from config.

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

Fails with a clear error (no partial state) if a cluster with that name already exists or drs_behavior is invalid. After creation, add hosts with cluster_add_host; change HA/DRS later with cluster_configure; verify with cluster_info. Audited to ~/.vmware/audit.db.

Args: name: Name for the new cluster; must be unique in the datacenter. datacenter: Datacenter name; omit to use the first datacenter on the target. ha: True enables vSphere HA (default False). drs: True enables DRS (default False). drs_behavior: "fullyAutomated" (default), "partiallyAutomated", or "manual". Only takes effect when drs=True. target: vCenter target name from config.yaml; omit to use the default target.

Returns: Status string confirming creation and which features (HA/DRS) were enabled.

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

Args: name: Name of the cluster to delete. target: Optional vCenter target name from config.

[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.

Args: name: Exact cluster name. target: vCenter target name from config.yaml; omit to use the default target.

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).

Args: cluster_name: Cluster to remove the host from. host_name: ESXi host name to remove. target: Optional vCenter target name from config.

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

After conversion the VM cannot be powered on — it serves as a clone source for deploy_vm_from_template.

Args: vm_name: Name of the VM to convert (must be powered off). target: Optional vCenter/ESXi target name from config.

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

The clone shares the source's base disk and writes changes to a copy-on-write delta disk, so it depends on the source VM staying intact. Fastest provisioning method for test/dev fleets; use vm_clone or deploy_vm_from_template for fully independent copies. Requires the source VM to have the named snapshot — run vm_list_snapshots first; unknown names return the available list. Audited to ~/.vmware/audit.db.

Args: source_vm_name: Exact name of the source VM (must have at least one snapshot). snapshot_name: Snapshot on the source to use as the clone base (from vm_list_snapshots). new_name: Name for the new linked clone; must not already exist. cpu: Override vCPU count; omit to keep the source's value. memory_mb: Override memory in MB; omit to keep the source's value. power_on: True powers the clone on after creation (default False). baseline_snapshot: If set, creates a snapshot with this name on the new clone. target: vCenter/ESXi target name from config.yaml; omit to use the default target.

Returns: Status string with the new clone name, or a snapshot/VM-not-found error.

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

Use for OVA appliance files on the local machine. For vSphere templates use deploy_vm_from_template; to copy an existing VM use vm_clone or deploy_linked_clone. Upload time scales with OVA size. Fails before creating anything if the datastore is not found. Audited to ~/.vmware/audit.db.

Args: ova_path: Local filesystem path to the .ova file (must be readable by this server). vm_name: Name for the new VM; must not already exist. datastore_name: Target datastore name; discover with browse_datastore. network_name: Port group for the VM's NICs (default "VM Network"). folder_path: vCenter VM folder path; omit to use the datacenter's root VM folder. power_on: True powers the VM on after import (default False). snapshot_name: If set, creates a baseline snapshot with this name after deploy. target: vCenter/ESXi target name from config.yaml; omit to use the default target.

Returns: Status string with the deployed VM name, or an error naming the missing resource.

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

Args: template_name: Name of the source vSphere template. new_name: Name for the new VM. datastore_name: Target datastore (uses template's datastore if omitted). cpu: Override CPU count (optional). memory_mb: Override memory in MB (optional). power_on: Power on after deployment. snapshot_name: Create a baseline snapshot with this name (optional). target: Optional vCenter/ESXi target name from config.

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

Returns alarms with severity (critical/warning/info), entity name and type, alarm name, acknowledged flag, and trigger time.

Args: target: Optional vCenter target name from config. Uses default if omitted. limit: Max number of alarms to return (None = all). Use when many alarms are active.

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

Uses AlarmManager.ClearTriggeredAlarms. The named alarm no longer appears in the active alarm list. Use this after resolving the underlying issue. Use list_vcenter_alarms to find entity_name and alarm_name values.

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). The response's 'scope' field states exactly what was cleared.

Args: entity_name: Name of the entity with the alarm (VM name, host name, or cluster name). alarm_name: Exact alarm definition name from list_vcenter_alarms output. target: Optional vCenter target name from config.

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

Results are cached locally in ~/.vmware-aiops/image_registry.json for fast lookup via list_cached_images. Run this to refresh the cache.

Args: target: Optional vCenter/ESXi target name from config.

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

Steps run sequentially. On failure: stops immediately, keeps the plan file with per-step results, and returns rollback_available flag. 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 if confirmed.

Args: plan_id: The plan ID returned by vm_create_plan. target: Optional vCenter/ESXi target name from config.

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

Args: vm_name: Name of the VM whose TTL should be cancelled.

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

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.

Args: vm_name: Name of the VM to revert. snapshot_name: Snapshot name to revert to (default: "baseline"). target: Optional vCenter/ESXi target name from config.

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

Args: vm_name: Source VM (or template) name. new_name: Name for the new clone. to_host: Target ESXi host name (default: source's host). to_datastore: Target datastore name (default: source's datastore). power_on: Power on the clone after creation. target: vCenter/ESXi target name from config.

[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 / deploy_vm_from_template / vm_clone for a ready-to-run guest. Fails before creating anything if the datastore is not found. Audited to ~/.vmware/audit.db.

Args: vm_name: Name for the new VM; must not already exist. cpu: vCPU count (default 2). memory_mb: Memory in MB (default 4096). disk_gb: Primary disk size in GB (default 40). network_name: Port group for the VM's NIC (default "VM Network"). datastore_name: Target datastore name; omit to use the first accessible datastore. folder_path: vCenter VM folder path; omit to use the datacenter's root VM folder. target: vCenter/ESXi target name from config.yaml; omit to use the default target.

Returns: Status string with the new VM name, or an error naming the missing resource.

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

Auto-triggered when operations involve 2+ steps or 2+ VMs. Validates actions, checks target existence in vSphere, and generates a plan with rollback info for each 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.

Example: operations=[ {"action": "power_off", "vm_name": "test-1"}, {"action": "revert_snapshot", "vm_name": "test-1", "snapshot_name": "baseline"}, {"action": "power_on", "vm_name": "test-1"} ]

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

Args: operations: List of operation dicts, each with "action" + params. target: Optional vCenter/ESXi target name from config.

[WRITE] Create a snapshot of a VM.

Args: vm_name: VM to snapshot. snapshot_name: Snapshot name. description: Optional description. memory: Include memory state (heavier, allows resume). quiesce: Quiesce guest filesystem (requires running VMware Tools). target: vCenter/ESXi target name from config.

[WRITE] Delete a VM (irreversible). VM must be powered off.

Args: vm_name: VM to delete. Must be powered off. target: vCenter/ESXi target name from config.

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

Frees disk space and does NOT change the VM's current state (unlike vm_revert_snapshot, which discards changes since the snapshot). Works while the VM is powered on. Run vm_list_snapshots first for exact names — unknown names return the available list. Irreversible: confirm with the user before calling. Audited to ~/.vmware/audit.db.

Snapshot consolidation is slow for old/large delta disks (often minutes). By default (wait=False) this fires the delete and returns a task id immediately so it does not block your context — poll completion with vm_task_status. Set wait=True only for small snapshots where you want the final confirmation inline (blocks up to 30 min, then returns the task id).

Args: vm_name: Exact name of the VM owning the snapshot. snapshot_name: Exact snapshot name from vm_list_snapshots output. remove_children: False (default) = children are kept and consolidated; True = delete the entire snapshot subtree below this one as well. wait: False (default) = async, return task id immediately; True = block on consolidation. target: vCenter/ESXi target name from config.yaml; omit to use the default target.

Returns: Status string with a task id (poll via vm_task_status), or a not-found message.

[READ] Download a file from a VM to local machine via VMware Tools.

Requires VMware Tools running in the guest OS.

Args: vm_name: Target VM name. guest_path: File path inside the guest to download. local_path: Local destination path. username: Guest OS username (default "root"). password: Guest OS password. target: Optional vCenter/ESXi target name from config.

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

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

Note: VMware Guest Ops API does not capture stdout/stderr directly. To capture output, redirect to a file and use vm_guest_download: command="/bin/bash", arguments="-c 'ls -la /tmp > /tmp/output.txt'" Then download /tmp/output.txt.

Args: vm_name: Target VM name. command: Full path to program (e.g. "/bin/bash", "C:\Windows\System32\cmd.exe"). arguments: Command arguments (e.g. "-c 'whoami'"). username: Guest OS username (default "root"). password: Guest OS password. working_directory: Working directory inside guest (optional). target: Optional vCenter/ESXi target name from config.

[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.

Returns exit_code, stdout, stderr, timed_out, os_family.

Args: vm_name: Target VM name. command: Shell command (e.g. "df -h", "ls /etc", "ipconfig"). username: Guest OS username (default "root"). password: Guest OS password. timeout: Max wait seconds (default 300). target: Optional vCenter/ESXi target name from config.

[WRITE] Provision a VM by running a sequence of guest operations (exec / upload / service).

Combines key injection, software installation, and service startup into a single call. Steps execute in order; stops on first failure.

Step types:

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

• upload: {"type": "upload", "local_path": "/tmp/id_rsa.pub", "guest_path": "/root/.ssh/authorized_keys"}

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

Args: vm_name: Target VM name. username: Guest OS username. password: Guest OS password. steps: Ordered list of step dicts. timeout: Per-step timeout in seconds (default 300). target: Optional vCenter/ESXi target name from config.

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

Example: steps = [ {"type": "upload", "local_path": "~/.ssh/id_rsa.pub", "guest_path": "/root/.ssh/authorized_keys"}, {"type": "exec", "command": "chmod 600 /root/.ssh/authorized_keys"}, {"type": "exec", "command": "apt-get install -y nginx"}, {"type": "service", "name": "nginx", "action": "enable"}, {"type": "service", "name": "nginx", "action": "start"}, ]

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

Requires VMware Tools running in the guest OS.

Args: vm_name: Target VM name. local_path: Local file path to upload. guest_path: Destination path inside the guest. username: Guest OS username (default "root"). password: Guest OS password. target: Optional vCenter/ESXi target name from config.

[READ] List all pending/failed plans.

Returns plan summaries (plan_id, created_at, status, steps count, VMs affected). Stale plans (>24h) are auto-cleaned.

[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. Returns an empty list when the VM has no snapshots.

Args: vm_name: Exact VM name as shown in vCenter inventory. target: vCenter/ESXi target name from config.yaml; omit to use the default target.

Returns: One dict per snapshot: name, description, created (timestamp), state (poweredOn/poweredOff at snapshot time), level (0 = root, higher = nesting depth). No pagination — snapshot trees are small.

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

Returns a list of TTL entries with remaining_minutes and expired flag.

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

If the target host has no access to the VM's current datastore, you MUST pass to_datastore — vCenter rejects cross-host vMotion without shared storage.

Args: vm_name: VM to migrate. to_host: Target ESXi host name. to_datastore: Target datastore (required for cross-storage hosts). target: vCenter/ESXi target name from config.

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

Graceful mode calls VMware Tools guest shutdown and waits up to 120s; if Tools is not running or shutdown stalls, the response tells you to retry with force=True. An already-off VM returns success without change. Audited to ~/.vmware/audit.db. Use vm_power_on to start a VM; vm_delete requires the VM to be off first.

Args: vm_name: Exact VM name as shown in vCenter inventory (case-sensitive). force: False (default) = graceful guest shutdown via VMware Tools; True = immediate hard power-off (risks guest filesystem damage). target: vCenter/ESXi target name from config.yaml; omit to use the default target.

Returns: Status string: shut down, force powered off, already off, or a Tools-unavailable hint.

[WRITE] Power on a virtual machine.

Args: vm_name: Exact name of the virtual machine. target: Optional vCenter/ESXi target name from config. Uses default if omitted.

[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). Audited to ~/.vmware/audit.db.

Args: vm_name: Exact name of the VM to reconfigure. cpu: New vCPU count; omit to leave unchanged. memory_mb: New memory in MB; omit to leave unchanged. target: vCenter/ESXi target name from config.yaml; omit to use the default target.

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).

Args: vm_name: VM to revert. snapshot_name: Snapshot to revert to. target: vCenter/ESXi target name from config.

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

Only call this after vm_apply_plan returns status='failed' and the user confirms they want to rollback. Irreversible steps (delete_vm, revert_snapshot, etc.) are skipped with a warning.

Args: plan_id: The plan ID of the failed plan. target: Optional vCenter/ESXi target name from config.

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

The scheduler daemon must be running (vmware-aiops daemon start) for automatic deletion. TTLs are persisted in ~/.vmware-aiops/ttl.json.

Args: vm_name: Name of the VM to auto-delete. minutes: Minutes until deletion (minimum 1). target: Optional vCenter/ESXi target name from config.

[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 to check whether the consolidation has finished, 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.

Args: task_id: The task id string returned by an async write operation. target: vCenter/ESXi target name from config.yaml; omit to use the default target.

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