id       = "libvirt"
name     = "libvirt"
homepage = "https://libvirt.org"
description = "A toolkit to interact with virtualization capabilities through a common API."
executables   = ["virsh", "virt-admin", "virt-host-validate"]

[dotfiles]

# libvirt's official client documentation names the per-user XDG files
# libvirt.conf and auth.conf. The latter can contain plaintext credentials and
# is therefore kept as a secret rule.
# https://libvirt.org/auth.html
# https://libvirt.org/uri.html
paths = ["[configHome]/libvirt/libvirt.conf"]
secret = ["[configHome]/libvirt/auth.conf"]

[commands]
format = 1
label = "virsh"
description = "Manage libvirt guest domains with virsh: list, start and gracefully shut down. The connect URI is a global option. virt-admin and virt-host-validate are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.source]]
id = "man"
kind = "manual"
url = "https://manpages.debian.org/unstable/libvirt-clients/virsh.1.en.html"
revision = "2026-10"
evidence = """
virsh [OPTION]... COMMAND [ARG]...
-c, --connect URI
Connect to the specified URI, as if by the connect command, instead of the default connection.
-r, --readonly
Make the initial connection read-only
-q, --quiet
Avoid extra informational messages.
"""

[[commands.field]]
id = "connect"
label = "Connection URI"
description = "For example qemu:///system or qemu:///session."
type = "string"
option = ["--connect", "-c"]
suggestions = [{ value = "qemu:///system", label = "QEMU system" }, { value = "qemu:///session", label = "QEMU session" }]
sources = ["man"]

[[commands.field]]
id = "readonly"
label = "Read-only connection"
type = "boolean"
option = ["--readonly", "-r"]
sources = ["man"]

[[commands.field]]
id = "quiet"
label = "Quiet"
type = "boolean"
option = ["--quiet", "-q"]
sources = ["man"]

[[commands.task]]
id = "readonly_session"
label = "Read-only connection"
fields = ["connect", "readonly", "quiet"]
required = ["connect"]
set = { readonly = [true] }

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["connect", "readonly", "quiet"]

[[commands.subcommand]]
path = ["list"]
label = "List domains"
description = "Print information about domains; running ones by default."

[[commands.subcommand.source]]
id = "man"
kind = "manual"
url = "https://manpages.debian.org/unstable/libvirt-clients/virsh.1.en.html"
revision = "2026-10"
evidence = """
list [--inactive | --all]
[--managed-save] [--title]
{ [--table] | --name | --id } [--uuid]
[--autostart] [--no-autostart]
[--state-running] [--state-paused]
[--state-shutoff] [--state-other]
Prints information about existing domains. If no options are specified it prints out information about running domains.
"""

[[commands.subcommand.field]]
id = "all"
label = "All domains"
type = "boolean"
option = ["--all"]
sources = ["man"]

[[commands.subcommand.field]]
id = "inactive"
label = "Inactive only"
type = "boolean"
option = ["--inactive"]
sources = ["man"]

[[commands.subcommand.field]]
id = "name"
label = "Names only"
type = "boolean"
option = ["--name"]
sources = ["man"]

[[commands.subcommand.field]]
id = "uuid"
label = "Show UUIDs"
type = "boolean"
option = ["--uuid"]
sources = ["man"]

[[commands.subcommand.field]]
id = "title"
label = "Show titles"
type = "boolean"
option = ["--title"]
sources = ["man"]

[[commands.subcommand.field]]
id = "autostart"
label = "Autostart only"
type = "boolean"
option = ["--autostart"]
sources = ["man"]

[[commands.subcommand.task]]
id = "list_all"
label = "List every domain"
fields = ["all", "uuid", "title"]
required = ["all"]
set = { all = [true] }

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["all", "inactive", "name"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["uuid", "title", "autostart"]

[[commands.subcommand]]
path = ["start"]
label = "Start a domain"
description = "Start a previously defined inactive domain."

[[commands.subcommand.source]]
id = "man"
kind = "manual"
url = "https://manpages.debian.org/unstable/libvirt-clients/virsh.1.en.html"
revision = "2026-10"
evidence = """
start domain-name-or-uuid [--console] [--paused]
[--autodestroy] [--bypass-cache] [--force-boot]
[--pass-fds N,M,...] [--reset-nvram]
Start a (previously defined) inactive domain
If --force-boot is specified, then any managedsave state is discarded and a fresh boot occurs.
"""

[[commands.subcommand.field]]
id = "domain"
label = "Domain"
description = "Domain name or UUID."
type = "string"
position = 0
sources = ["man"]

[[commands.subcommand.field]]
id = "console"
label = "Attach to console"
type = "boolean"
option = ["--console"]
sources = ["man"]

[[commands.subcommand.field]]
id = "paused"
label = "Start paused"
type = "boolean"
option = ["--paused"]
sources = ["man"]

[[commands.subcommand.field]]
id = "force_boot"
label = "Force fresh boot"
description = "Discards any managedsave state."
type = "boolean"
option = ["--force-boot"]
effect = "delete"
sources = ["man"]

[[commands.subcommand.task]]
id = "start_domain"
label = "Start a domain"
fields = ["domain", "console", "paused"]
required = ["domain"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["domain", "console", "paused"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["force_boot"]

[[commands.subcommand]]
path = ["shutdown"]
label = "Shut down a domain"
description = "Gracefully shut down a domain; there is no guarantee it succeeds."

[[commands.subcommand.source]]
id = "man"
kind = "manual"
url = "https://manpages.debian.org/unstable/libvirt-clients/virsh.1.en.html"
revision = "2026-10"
evidence = """
shutdown domain [--mode MODE-LIST]
Gracefully shuts down a domain.
the --mode parameter can specify a comma separated list which includes acpi, agent, initctl, signal and paravirt.
"""

[[commands.subcommand.field]]
id = "domain"
label = "Domain"
description = "Domain name or UUID."
type = "string"
position = 0
sources = ["man"]

[[commands.subcommand.field]]
id = "mode"
label = "Shutdown mode"
description = "Comma-separated list of methods to try."
type = "string"
option = ["--mode"]
suggestions = [{ value = "acpi", label = "ACPI" }, { value = "agent", label = "Guest agent" }, { value = "initctl", label = "initctl" }, { value = "signal", label = "Signal" }, { value = "paravirt", label = "Paravirt" }]
sources = ["man"]

[[commands.subcommand.task]]
id = "shutdown_domain"
label = "Shut down a domain"
fields = ["domain", "mode"]
required = ["domain"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["domain", "mode"]