kyvernon vm

`kyvernon vm`

Virtual machine operations

Usage

kyvernon vm <COMMAND>

Subcommands: power-on, power-off, shutdown, reset, suspend, delete, create, reconfigure, serial-log, snapshot, console, guest-agent-offer, clone, mark-as-template, mark-as-vm, unregister, backup, register, customize, relocate, resolve-migration, export, guest

`kyvernon vm power-on`

Power on

Usage

kyvernon vm power-on [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id (vm-N)	yes
`--wait`	Wait for the task to finish and print it
`--idempotency-key`	Idempotency key (a retry with the same key returns the same task)

API operation: POST /v1/vms/{id}/power-on

`kyvernon vm power-off`

Power off hard, at once (the guest is not asked; see shutdown)

Usage

kyvernon vm power-off [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id (vm-N)	yes
`--wait`	Wait for the task to finish and print it
`--idempotency-key`	Idempotency key (a retry with the same key returns the same task)

API operation: POST /v1/vms/{id}/power-off

`kyvernon vm shutdown`

Shut down gracefully: the guest is asked to power off; after the timeout the VM is powered off hard

Usage

kyvernon vm shutdown [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id (vm-N)	yes
`--timeout`	Seconds the guest gets before the hard power-off (default 90)
`--wait`	Wait for the task to finish and print it
`--idempotency-key`	Idempotency key (a retry with the same key returns the same task)

API operation: POST /v1/vms/{id}/shutdown

`kyvernon vm reset`

Reset

Usage

kyvernon vm reset [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id (vm-N)	yes
`--wait`	Wait for the task to finish and print it
`--idempotency-key`	Idempotency key (a retry with the same key returns the same task)

API operation: POST /v1/vms/{id}/reset

`kyvernon vm suspend`

Suspend

Usage

kyvernon vm suspend [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id (vm-N)	yes
`--wait`	Wait for the task to finish and print it
`--idempotency-key`	Idempotency key (a retry with the same key returns the same task)

API operation: POST /v1/vms/{id}/suspend

`kyvernon vm delete`

Delete (must be powered off)

Usage

kyvernon vm delete [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id (vm-N)	yes
`--wait`	Wait for the task to finish and print it
`--idempotency-key`	Idempotency key (a retry with the same key returns the same task)

API operation: DELETE /v1/vms/{id}

`kyvernon vm create`

Create from a JSON spec (VirtualMachine schema)

Usage

kyvernon vm create [OPTIONS]

Argument	Description	Required
`--folder`	VM folder id (group-vN)	yes
`--spec`	Path to the spec JSON (VirtualMachine schema; `-` for stdin)	yes
`--host`	Host to place it on
`--create-disk`	Disk files to create first, as JSON (`DiskFileRequest` schema; repeat)
`--firmware`	Firmware, replacing `config.firmware` of the spec values `bios`, `efi`
`--wait`	Wait for the task to finish and print it
`--idempotency-key`	Idempotency key (a retry with the same key returns the same task)

API operation: POST /v1/vms

`kyvernon vm reconfigure`

Reconfigure from a JSON config (VmConfig schema); optionally rename

Usage

kyvernon vm reconfigure [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--config`	Path to the config JSON (`-` for stdin)	yes
`--name`	New name
`--create-disk`	Disk files to create (`DiskFileRequest` JSON; repeat)
`--grow-disk`	Disk files to grow (`DiskFileRequest` JSON; repeat)
`--delete-disk`	Disk files to delete (`DiskFileRequest` JSON; repeat)
`--firmware`	Firmware, replacing `firmware` of the config (the VM must be powered off) values `bios`, `efi`
`--wait`	Wait for the task to finish and print it
`--idempotency-key`	Idempotency key (a retry with the same key returns the same task)

API operation: POST /v1/vms/{id}/reconfigure

`kyvernon vm serial-log`

Tail of the serial console log

Usage

kyvernon vm serial-log [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--max-bytes`	Bytes from the end

API operation: GET /v1/vms/{id}/serial-log

`kyvernon vm snapshot`

Snapshots

Usage

kyvernon vm snapshot <COMMAND>

Subcommands: create, revert, remove, remove-all, rename

`kyvernon vm snapshot create`

Create a snapshot

Usage

kyvernon vm snapshot create [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--name`	Name	yes
`--description`	Description
`--memory`	Include the memory state
`--quiesce`	Quiesce the guest file systems
`--wait`	Wait for the task to finish and print it
`--idempotency-key`	Idempotency key (a retry with the same key returns the same task)

API operation: POST /v1/vms/{id}/snapshots

`kyvernon vm snapshot revert`

Revert to a snapshot

Usage

kyvernon vm snapshot revert [OPTIONS] <ID> <KEY>

Argument	Description	Required
`<ID>`	VM id	yes
`<KEY>`	Snapshot key	yes
`--suppress-power-on`	Stay powered off even if the snapshot was taken powered on
`--wait`	Wait for the task to finish and print it
`--idempotency-key`	Idempotency key (a retry with the same key returns the same task)

API operation: POST /v1/vms/{id}/snapshots/{key}/revert

`kyvernon vm snapshot remove`

Remove a snapshot

Usage

kyvernon vm snapshot remove [OPTIONS] <ID> <KEY>

Argument	Description	Required
`<ID>`	VM id	yes
`<KEY>`	Snapshot key	yes
`--children`	Also remove child snapshots
`--wait`	Wait for the task

API operation: DELETE /v1/vms/{id}/snapshots/{key}

`kyvernon vm snapshot remove-all`

Remove every snapshot

Usage

kyvernon vm snapshot remove-all [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--wait`	Wait for the task

API operation: DELETE /v1/vms/{id}/snapshots

`kyvernon vm snapshot rename`

Rename a snapshot (display name and/or description)

Usage

kyvernon vm snapshot rename [OPTIONS] <ID> <KEY>

Argument	Description	Required
`<ID>`	VM id	yes
`<KEY>`	Snapshot key	yes
`--name`	New display name
`--description`	New description (empty string clears it)

API operation: POST /v1/vms/{id}/snapshots/{key}/rename

`kyvernon vm console`

Graphical console: tickets and screenshots

Usage

kyvernon vm console <COMMAND>

Subcommands: ticket, screenshot

`kyvernon vm console ticket`

Issue a single-use console ticket (30 s) for the WebSocket at /v1/console/{ticket}

Usage

kyvernon vm console ticket <ID>

Argument	Description	Required
`<ID>`	VM id	yes

API operation: POST /v1/vms/{id}/console/ticket

`kyvernon vm console screenshot`

Save a PNG screenshot of the console

Usage

kyvernon vm console screenshot [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--max-width`	Scale the image down to this width in pixels
`--to`	Output file (default: `<id>.png`)

API operation: GET /v1/vms/{id}/console/screenshot

`kyvernon vm guest-agent-offer`

Whether to offer installing the guest agent for a VM created from a template

Usage

kyvernon vm guest-agent-offer <TEMPLATE>

Argument	Description	Required
`<TEMPLATE>`	Template, image name or guest OS (`ubuntu-24.04`, `debian-13`, `ubuntu64Guest`)	yes

API operation: POST /v1/guest-agent/offer

`kyvernon vm clone`

Clone

Usage

kyvernon vm clone [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	Source VM id	yes
`--name`	Name of the clone	yes
`--folder`	Target folder (default: the source's)
`--resource-pool`	Target resource pool
`--host`	Target host
`--datastore`	Target datastore
`--linked`	Linked clone from `--snapshot`
`--snapshot`	Snapshot key to clone from
`--power-on`	Power the clone on
`--template`	Make the clone a template
`--wait`	Wait for the task to finish and print it
`--idempotency-key`	Idempotency key (a retry with the same key returns the same task)

API operation: POST /v1/vms/{id}/clone

`kyvernon vm mark-as-template`

Mark a powered-off VM as a template

Usage

kyvernon vm mark-as-template <ID>

Argument	Description	Required
`<ID>`	VM id	yes

API operation: POST /v1/vms/{id}/mark-as-template

`kyvernon vm mark-as-vm`

Convert a template back to a VM

Usage

kyvernon vm mark-as-vm [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--resource-pool`	Resource pool
`--host`	Host

API operation: POST /v1/vms/{id}/mark-as-vm

`kyvernon vm unregister`

Remove from the inventory, keeping the disk files

Usage

kyvernon vm unregister <ID>

Argument	Description	Required
`<ID>`	VM id	yes

API operation: POST /v1/vms/{id}/unregister

`kyvernon vm backup`

Back the VM up to the backup repository now (a task)

Usage

kyvernon vm backup [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--quiesce`	Quiescing: NONE, PREFERRED or REQUIRED (default: the backup settings)
`--full`	Transfer every allocated area even when an incremental backup is possible
`--wait`	Wait for the task

API operation: POST /v1/backup/points

`kyvernon vm register`

Usage

kyvernon vm register [OPTIONS]

Argument	Description	Required
`--folder`	Destination VM folder (`group-vN`)	yes
`--path`	Datastore path (`[ds] name/name.vmx`)	yes
`--name`	Display name (defaults to the on-disk manifest name)
`--as-template`	Register as a template
`--resource-pool`	Resource pool (`resgroup-N`; required unless `--as-template`)
`--host`	Host (`host-N`)
`--wait`	Wait for the task to finish and print it
`--idempotency-key`	Idempotency key (a retry with the same key returns the same task)

API operation: POST /v1/vms/register

`kyvernon vm customize`

Apply a named customization specification (powered-off VM)

Usage

kyvernon vm customize [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--spec`	Catalogue specification name	yes
`--wait`	Wait for the task to finish and print it
`--idempotency-key`	Idempotency key (a retry with the same key returns the same task)

API operation: POST /v1/vms/{id}/customize

`kyvernon vm relocate`

Relocate a VM (host / pool / folder / cold storage datastore)

Usage

kyvernon vm relocate [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--host`	Destination host (`host-N`)
`--resource-pool`	Destination resource pool (`resgroup-N`)
`--folder`	Destination VM folder (`group-vN`)
`--datastore`	Destination datastore for cold storage relocate (`datastore-N`)
`--disk`	Per-disk locator `KEY=datastore-N` (repeatable; cold relocate only)
`--nic`	Ethernet rebind `KEY=network-N` (repeatable; RelocateVM deviceChange)
`--wait`	Wait for the task to finish and print it
`--idempotency-key`	Idempotency key (a retry with the same key returns the same task)

API operation: POST /v1/vms/{id}/relocate

`kyvernon vm resolve-migration`

Resolve a VM fenced after a migration with an unknown outcome

Usage

kyvernon vm resolve-migration [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--resolution`	Who keeps the guest: `source-keeps` or `destination-keeps`	yes
`--host`	Destination host (`host-N`); required with `destination-keeps`

API operation: POST /v1/vms/{id}/resolve-migration

`kyvernon vm export`

Export a VM over a native NFC lease (POST /v1/vms/{id}/export)

Usage

kyvernon vm export <ID>

Argument	Description	Required
`<ID>`	VM id	yes

API operation: POST /v1/vms/{id}/export

`kyvernon vm guest`

Guest operations through the guest agent

Usage

kyvernon vm guest <COMMAND>

Subcommands: validate, acquire, release, start, list, terminate, env, read-file, write-file, list-files, mkdir, delete-file, rmdir, move-file, move-dir, change-attrs, temp-file, temp-dir

`kyvernon vm guest validate`

Probe whether guest operations are available (ValidateCredentialsInGuest)

Usage

kyvernon vm guest validate [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--username`	Guest username (accepted, not checked)

API operation: POST /v1/vms/{id}/guest/credentials/validate

`kyvernon vm guest acquire`

Acquire guest credentials echo (AcquireCredentialsInGuest)

Usage

kyvernon vm guest acquire [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--username`	Guest username (accepted, not checked)

API operation: POST /v1/vms/{id}/guest/credentials/acquire

`kyvernon vm guest release`

Release guest credentials (ReleaseCredentialsInGuest)

Usage

kyvernon vm guest release <ID>

Argument	Description	Required
`<ID>`	VM id	yes

API operation: POST /v1/vms/{id}/guest/credentials/release

`kyvernon vm guest start`

Start a program in the guest

Usage

kyvernon vm guest start [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--program`	Program path in the guest	yes
`--arguments`	Arguments (one string)
`--username`	Guest username (accepted, not checked)

API operation: POST /v1/vms/{id}/guest/processes

`kyvernon vm guest list`

List guest processes started through guest ops

Usage

kyvernon vm guest list [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--pid`	Filter to these process ids

API operation: GET /v1/vms/{id}/guest/processes

`kyvernon vm guest terminate`

Terminate a guest process

Usage

kyvernon vm guest terminate <ID> <PID>

Argument	Description	Required
`<ID>`	VM id	yes
`<PID>`	Process id	yes

API operation: DELETE /v1/vms/{id}/guest/processes/{pid}

`kyvernon vm guest env`

Read guest environment variables

Usage

kyvernon vm guest env [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--name`	Variable names (empty: all)

API operation: GET /v1/vms/{id}/guest/environment

`kyvernon vm guest read-file`

Read a file from the guest (Base64 in the JSON response)

Usage

kyvernon vm guest read-file [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--path`	Path in the guest	yes

API operation: POST /v1/vms/{id}/guest/files/read

`kyvernon vm guest write-file`

Write a file into the guest from a local file (Base64-encoded on the wire)

Usage

kyvernon vm guest write-file [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--path`	Path in the guest	yes
`--from`	Local file to upload	yes
`--no-overwrite`	Refuse to overwrite an existing guest file

API operation: POST /v1/vms/{id}/guest/files/write

`kyvernon vm guest list-files`

List files or directory children in the guest

Usage

kyvernon vm guest list-files [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--path`	Directory or file path in the guest	yes
`--index`	Zero-based start index
`--max-results`	Cap on returned entries
`--match-pattern`	Basename regex (`grep -E`)

API operation: POST /v1/vms/{id}/guest/files/list

`kyvernon vm guest mkdir`

Create a directory in the guest

Usage

kyvernon vm guest mkdir [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--path`	Directory path in the guest	yes
`--parents`	Create missing parents

API operation: POST /v1/vms/{id}/guest/files/mkdir

`kyvernon vm guest delete-file`

Delete a file in the guest (not a directory)

Usage

kyvernon vm guest delete-file [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--path`	File path in the guest	yes

API operation: POST /v1/vms/{id}/guest/files/delete

`kyvernon vm guest rmdir`

Delete a directory in the guest

Usage

kyvernon vm guest rmdir [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--path`	Directory path in the guest	yes
`--recursive`	Remove contents too

API operation: POST /v1/vms/{id}/guest/files/rmdir

`kyvernon vm guest move-file`

Move or rename a file in the guest

Usage

kyvernon vm guest move-file [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--src`	Source path in the guest	yes
`--dst`	Destination path in the guest	yes
`--overwrite`	Replace an existing destination file

API operation: POST /v1/vms/{id}/guest/files/move

`kyvernon vm guest move-dir`

Move or rename a directory in the guest

Usage

kyvernon vm guest move-dir [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--src`	Source directory path in the guest	yes
`--dst`	Destination directory path in the guest	yes

API operation: POST /v1/vms/{id}/guest/files/move-dir

`kyvernon vm guest change-attrs`

Change posix file attributes in the guest

Usage

kyvernon vm guest change-attrs [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--path`	Path in the guest	yes
`--owner-id`	Owner uid
`--group-id`	Group gid
`--permissions`	Mode bits as VMware permissions (e.g. 420 = 0644)
`--access-time-unix`	Access time, Unix seconds
`--modification-time-unix`	Modification time, Unix seconds

API operation: POST /v1/vms/{id}/guest/files/attrs

`kyvernon vm guest temp-file`

Create a temporary file in the guest

Usage

kyvernon vm guest temp-file [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--prefix`	Name prefix (no path separators)
`--suffix`	Name suffix (no path separators)
`--directory-path`	Parent directory (default guest `/tmp`)

API operation: POST /v1/vms/{id}/guest/files/temp-file

`kyvernon vm guest temp-dir`

Create a temporary directory in the guest

Usage

kyvernon vm guest temp-dir [OPTIONS] <ID>

Argument	Description	Required
`<ID>`	VM id	yes
`--prefix`	Name prefix (no path separators)
`--suffix`	Name suffix (no path separators)
`--directory-path`	Parent directory (default guest `/tmp`)

API operation: POST /v1/vms/{id}/guest/files/temp-dir