CLI and API reference (hv manual)

CLI and API reference

The hv CLI, JSON API and MCP server expose management operations with the same domain concepts as the console. Use them for repeatable administration and integration. Before sending mutations, identify the Pool and Project, obtain the required Account rights and establish a trusted connection to the intended installation.

Use the CLI

The installed Host includes hv. For a workstation, obtain a release-matched CLI from your release operator. Commands used throughout this manual are collected below; hv --help plus subcommand help describes the installed binary.

Local commands use the configured database and default to the privileged System actor. Select production configuration explicitly:

HV_ENV=prod hv pool list --config /etc/hv/prod.toml
HV_ENV=prod hv vm list --config /etc/hv/prod.toml --pool POOL --json

Remote commands use the JSON API and the token's Account. A private file supplied by the administrator can provide the token without putting it in arguments:

hv vm show VM --pool POOL --server https://hv.example.com:8443 --token-stdin < /secure/hv-api-token

HV_SERVER and HV_TOKEN are supported alternatives. Do not use token stdin with a command that already reads a password from stdin. --ca-file adds a trusted private CA; do not disable verification to solve an unidentified certificate mismatch.

Most selectors accept a reference, UUID or unambiguous name. Use --pool when more than one Pool exists. hv project use NAME selects a default Project; explicit --project avoids ambiguity in automation. Fleet roles may select another Silo with --silo.

Exit codes are 0 for success, 1 for operation failure, 2 for usage/refused input, 3 for denied access and 4 for not found. Success can mean a Task was queued; use hv task show TASK_ID to inspect completion.

Use the JSON API

The API base is /api/v1 on the administration endpoint. Authenticated requests carry an Account bearer token. A 404 can mean an object is hidden; a 403 means the action is not allowed on a visible target.

Follow returned Tasks until they finish. Supported create/import operations accept Idempotency-Key to replay the same request within the retention period without duplicating it. Reusing the key for different input is refused. Do not assume every mutation is idempotent or retry an ambiguous disk operation blindly.

Connect MCP

The MCP server also requires an Account token. A local stdio configuration uses:

hv mcp serve --config /etc/hv/prod.toml --stdio

Supply HV_MCP_TOKEN through the client's protected environment. Default MCP mode shares a running engine; --engine starts its own execution engine and must not compete with hv server on the same database. HTTP mode exposes a separate /mcp listener and requires appropriate TLS for non-loopback access.

Mutation tools request human confirmation when the client supports elicitation. Otherwise the tool requires confirm: true; neither mechanism bypasses authorization. Inspect the exact target and resulting Task.

Common problems

Queued work needs an engine even when a local command can read inventory. Wrong configuration can select another database. Remote restores/imports have mode-specific requirements in their help. For denied operations, correct Account roles and token scopes together. Verify a read-only inventory query before allowing an automation client to change workloads.

Select a command and check its result

Use hv --help to find a command family and the selected subcommand's --help to review its required arguments. The commands below are the ones used in the manual's procedures. Keep the connection and authentication options from the beginning of this chapter when adapting an example to your deployment. Names such as VM, HOST and POOL must be replaced with actual selectors; they are not literal object names to create.

Select a command and check its result
Operation	Command or command family	Result to check
List Pools	`hv pool list`	The intended Pool is present in this deployment.
List or inspect VMs	`hv vm list --pool POOL` or `hv vm show VM --pool POOL`	Ownership, power state and resident Host match the target.
Start a VM	`hv vm start VM --pool POOL`	The VM runs and its operating system boots.
Shut down or reboot a VM	`hv vm shutdown VM --pool POOL` or `hv vm reboot VM --pool POOL`	The guest responds and reaches the requested state.
Delete a VM	`hv vm delete VM --pool POOL`	Review disk consequences before confirmation; inspect inventory afterward.
Move a running VM	`hv vm migrate VM --pool POOL --host DESTINATION_HOST --live`	The Task finishes and the resident Host changes.
Enter or leave maintenance	`hv host maintenance enter HOST --pool POOL` or `hv host maintenance exit HOST --pool POOL`	Inspect remaining VMs and the Host's enabled state.
Inspect or reboot a Host	`hv host show HOST --pool POOL` or `hv host reboot HOST --pool POOL`	Reboot only after confirming workload evacuation.
Request PV dom0	`hv host dom0-mode HOST pv --pool POOL`	The mode changes at the next boot, not immediately.
Change Pool membership or coordinator	`hv pool eject` or `hv pool designate-master`	Review subcommand help and the Host procedure before changing the target.
Inspect Networks	`hv net list --pool POOL` or `hv net show NETWORK --pool POOL`	Check the selected Network's physical or overlay connections.
Create a Network	`hv net create --pool POOL --name isolated --mtu 1500`	A Network record does not supply external routing.
Replace overlay rules	`hv net sdn acl set`	Supply the complete intended ruleset; review subcommand help for input format.
Inspect storage	`hv sr list --pool POOL` or `hv sr show SR --pool POOL`	Check capacity and Host attachments.
Create storage	`hv sr create`	Review the kind-specific arguments and destructive effects before running it.
Refresh storage inventory	`hv sr scan SR --pool POOL`	A scan refreshes records; it does not repair damaged data.
Remove storage	`hv sr forget` or `hv sr destroy`	Forget removes registration; destroy removes repository data.
Inspect Tasks	`hv task list --pool POOL` or `hv task show TASK_ID`	Read the final state and diagnostic, not only submission success.
Inspect backup configuration	`hv backup job show JOB`	Review the selected VMs, Remote, schedule and retention.
Run and inspect a backup	`hv backup job run JOB`, `hv backup run list --job JOB`, `hv backup run show RUN_ID`	Follow the run and identify its recovery point.
List and restore points	`hv backup points` or `hv backup restore`	Use remote mode and the destination UUIDs described in backups.
Verify audit history	`hv audit verify`	Preserve diagnostics and independent anchors if verification fails.

Cross-Pool migration adds --dest-pool DESTINATION_POOL and can repeat --network-map VIF=NETWORK. This path uses the destination Pool's default SR. Do not pass Network mappings for a same-Pool migration. Check storage and each NIC's destination before submitting either kind of move.

The backup procedure gives complete examples for hv backup remote add, hv backup retention set and hv backup job create. A five-field schedule uses UTC. A Remote path for a local-directory job is on the engine's machine, not the workstation issuing the command.

Use host-local tools

These tools act on the Host where they run. Use a console or an authorized shell on the intended machine and confirm its identity before making changes. They do not inherit a remote hv --server destination.

Use host-local tools
Tool	Purpose and check
`rc-status` and `rc-service SERVICE status`	Inspect OpenRC services. Use the service names in first boot and security.
`xl info`	Inspect the running Xen system when diagnosing Host boot.
`ip address` and `ip route`	Inspect the management address and route without changing them.
`hv setup-token`	Issue a replacement setup token while no Account exists; keep its output private.
`hv-agent pool join-code`	Produce a one-use public join code valid for 15 minutes.
`hv-agent mesh status`	Inspect mesh peers and handshake information.
`hv-upgrade status`	Inspect update slots and their state.
`hv-upgrade rollback --dry-run`	Preview the local rollback before selecting it.
`hv-upgrade rollback`	Change the next boot selection; this command does not reboot by itself.
`hv-installer --answers /root/answers.toml --dry-run`	Validate answers and display the installation plan without executing it.
`hv-installer --answers /root/answers.toml`	Execute that installation, erasing the selected disk without another erase question.

Before an unattended install, stop the automatic installer with rc-service hv-installer-live stop; two installers must not operate on the disk together. Follow installation for the order of preparation, review and execution. A dry-run checks the plan, not whether the finished machine can boot.

Write installation media from a workstation

The dd examples in installation run on the workstation holding the ISO, not on the target Host. if= names the source image and of= names the whole destination USB device. The block size differs in spelling between the Linux example, bs=4M, and the macOS example, bs=4m. Linux conv=fsync flushes the output before completion; wait for the subsequent sync command as well.

On macOS, diskutil list identifies disks, diskutil unmountDisk unmounts the chosen disk and diskutil eject ejects it after writing and synchronization. Check each command's result before continuing. These commands can overwrite a workstation disk if given the wrong destination. Never copy a placeholder device name into a command without first replacing it with the verified USB device.