delonix vm

Usage: dlx vm [OPTIONS] <COMMAND>

Commands:
  dash       Dashboard (KPIs + table) of the VMs — interactive TUI, or `--once` snapshot
  init       Bootstrap a project with a VM manifest — files ALREADY FILLED IN (images included), ready to use without editing anything
  create     Create (or auto-recover) a VM
  build      Build a qcow2 VM image from a `VMfile`
  pull       Pull a golden VM image from an OCI registry — with no argument, the OFFICIAL Delonix image (ready for `vm create`/`cluster kubeadm`)
  ls-remote  List the tags available in a remote OCI repository — with no argument, the OFFICIAL Delonix golden image repo (discover which k8s versions are published before `pull`)
  push       Push a local golden VM image to an OCI registry (`vm push <name> <target>`)
  ls         List the VMs
  console    Attach to the VM's serial console (interactive terminal) — works with no IP (boot logs, login). Escape: Ctrl-] 
  vnc        Print the VNC address of a graphical VM (created with `--vnc`, libvirt)
  status     Current state (reconciles liveness/IP with the backend)
  reach      
  bridge     EXPERIMENTAL (root): give a libvirt VM DIRECT IP reachability to a container SDN network (veth from the host into the holder netns + routes). Defaults to a DRY-RUN; add `--apply` (as root) to establish it
  unbridge   Tear down a `vm bridge` (dry-run without `--apply`)
  describe   Human-readable detail of one or more VMs, `kubectl describe` style (for humans; use `status` for the usual compact view). Includes the LIVE state — `delonix_vm::status` reconciles liveness/IP with the backend
  stop       Stop the VM (preserves disk/record)
  start      Start an existing, stopped VM — idempotent (already running = no-op). Reboots with the base disk/vcpus/memory/network/backend recorded at its last `create`/`start`, reusing the same overlay (disk state preserved). Does NOT restore anything that only ever existed as a `vm create` flag (custom kernel/seed/volumes/static IP/VNC/advanced libvirt knobs) — a VM using those needs the original `vm create` invocation instead (also idempotent/auto-heal)
  restart    Stop (if running) then start — always a real reboot, unlike `start`. Same recovered-fields limits as `start`
  rm         Remove the VM (stops + deletes overlay/state)
  snapshot   Take a named snapshot (libvirt: a running VM's snapshot is a system checkpoint — memory + disk; `restore` reverts to it). Not yet supported on the cloud-hypervisor backend
  restore    Revert the VM to a named snapshot
  snapshots  List the VM's snapshots
  apply      Apply the `kind: Vm` documents of a manifest (`delonix_vm::create` is already idempotent by name — creates or auto-recovers)
  help       Print this message or the help of the given subcommand(s)

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm snapshots [OPTIONS] <NAME>

Arguments:
  <NAME>  

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm restore [OPTIONS] <NAME> <SNAPSHOT>

Arguments:
  <NAME>      
  <SNAPSHOT>  Snapshot name to revert to

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm snapshot [OPTIONS] <NAME> <SNAPSHOT>

Arguments:
  <NAME>      
  <SNAPSHOT>  Snapshot name

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm restart [OPTIONS] <NAME>

Arguments:
  <NAME>  

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm start [OPTIONS] <NAME>

Arguments:
  <NAME>  

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm describe [OPTIONS] <NAMES>...

Arguments:
  <NAMES>...  

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm unbridge [OPTIONS] <NETWORK>

Arguments:
  <NETWORK>  

Options:
      --apply         
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm bridge [OPTIONS] <NETWORK>

Arguments:
  <NETWORK>  

Options:
      --l18n <en|pt>           Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
      --vm-subnet <VM_SUBNET>  VM subnet(s) to route back (default: auto-detected `virbr*`). Repeatable
      --apply                  Actually run the privileged plan (requires root). Without it: dry-run
  -h, --help                   Print help

Usage: dlx vm reach [OPTIONS]

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm vnc [OPTIONS] <NAME>

Arguments:
  <NAME>  

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm console [OPTIONS] <NAME>

Arguments:
  <NAME>  

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm push [OPTIONS] <NAME> <TARGET>

Arguments:
  <NAME>    
  <TARGET>  

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm ls-remote [OPTIONS] [SOURCE]

Arguments:
  [SOURCE]  

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
      --no-k8s        With no `source`, list the official NO-Kubernetes golden's repo instead of the Kubernetes one
  -h, --help          Print help

Usage: dlx vm pull [OPTIONS] [SOURCE]

Arguments:
  [SOURCE]  OCI reference (default: the official Delonix image)

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
      --name <NAME>   Local name (default: derived from the reference)
      --no-k8s        With no `source`, pull the official NO-Kubernetes golden (just the `delonix` engine, rootless-ready) instead of the Kubernetes one
  -h, --help          Print help

Usage: dlx vm build [OPTIONS] --tag <TAG> [CONTEXT]

Arguments:
  [CONTEXT]  Build context — the directory `COPY` reads from [default: .]

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -t, --tag <TAG>     
  -f, --file <FILE>   The `VMfile` (default: `<context>/VMfile`)
      --no-compress   Do not compress the final qcow2
      --network       Give the guest network access during `RUN` (for `apt-get install` and friends). Off by default: a build that reaches the internet produces a different image depending on when it ran
  -h, --help          Print help

Usage: dlx vm init [OPTIONS] [DIR]

Arguments:
  [DIR]  Project directory (default: the current one) [default: .]

Options:
      --l18n <en|pt>         Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
      --name <NAME>          Project name (default: the directory name)
      --image <IMAGE>        Image to use. Omit = fills in with the default image
      --force                Overwrite existing files
      --vmfile               Scaffold a `VMfile` for BUILDING your own qcow2 image, instead of a manifest for RUNNING an existing one. The two are different jobs and this is the same verb for both: `init` starts a project either way
  -t, --template <TEMPLATE>  Generate a complete PROJECT for a stack (e.g. `python`) with best practices, instead of the generic scaffold. `--template list` shows the available ones
      --up                   After generating, build the image, start it, and wait until healthy
  -h, --help                 Print help

Usage: dlx vm dash [OPTIONS]

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
      --once          
      --json          
  -h, --help          Print help

Usage: dlx vm create [OPTIONS] <NAME>

Arguments:
  <NAME>
          

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --url-img <URL_IMG>
          Absolute URL of a qcow2 cloud image to boot this VM from.
          
          Downloaded once and cached, so a second `create` from the same URL costs nothing. Verified against a sibling `<url>.sha256` when the publisher offers one; without it, the download is trusted on TLS alone and SAYS SO — someone pointing this at their own bucket deserves to know which of the two they got.

      --disk <DISK>
          Base disk (qcow2/raw) — becomes a per-VM overlay. Omit to use the local golden VM image (if there is exactly one; `image --vm ls`)

      --vcpus <VCPUS>
          [default: 1]

      --memory <MEMORY>
          Memory (`"2G"`/`"1024M"`)
          
          [default: 1G]

      --network <NETWORK>
          Ingress network for the tap (default: the system ingress network; a custom network must be created first with `delonix network create`)
          
          [default: ingress]

      --namespace <NAMESPACE>
          Isolation namespace (default `default`): VMs of different namespaces do not reach each other. Requires `--backend cloud-hypervisor`

      --kernel <KERNEL>
          Kernel for direct boot

      --initrd <INITRD>
          

      --firmware <FIRMWARE>
          Firmware, alternative to the kernel (cloud images)

      --cmdline <CMDLINE>
          

      --seed <SEED>
          Ready-made cloud-init (NoCloud) ISO — if given, takes priority over `--hostname`/`--ssh-key`/`--user-data` (those generate the ISO; this uses it directly)

      --hostname <HOSTNAME>
          Hostname to apply on first boot (generates the NoCloud ISO if no explicit `--seed` is given)

      --ssh-key <SSH_KEYS>
          Authorized public SSH key, `ssh-ed25519 AAAA...` or `@path` to read from a file. Repeatable

      --user-data <USER_DATA>
          Your own cloud-init `user-data` (fully replaces the default-generated one) — full control for whoever needs it

      --restart-policy <RESTART_POLICY>
          `no`|`on-failure`|`always`

      --hugepages
          

      --cpu-affinity <CPU_AFFINITY>
          Core affinity, e.g. `8-15`

      --device <DEVICES>
          VFIO PCI passthrough, repeatable

      --backend <BACKEND>
          `cloud-hypervisor`|`libvirt` (omit = auto-detection)

      --net-mode <NET_MODE>
          libvirt only: `user`|`nat`|`bridge`

      --bridge <BRIDGE>
          Bridge name (net-mode=bridge) or libvirt network (nat)

      --ip <IP>
          Static IP (libvirt nat mode): DHCP reservation on the libvirt network

      --vnc
          VNC graphical console (libvirt backend only — Cloud Hypervisor has no display)

      --console
          After starting, attach to the serial console to watch the boot live (Ctrl-] to detach)

      --wait
          After starting, wait (with a spinner) until the VM has an IP, up to --boot-timeout

      --boot-timeout <BOOT_TIMEOUT>
          Seconds to wait with --wait (default 120)
          
          [default: 120]

  -h, --help
          Print help (see a summary with '-h')

Usage: dlx vm ls [OPTIONS]

Options:
      --l18n <en|pt>     Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
      --ports            Also probe a short list of well-known ports (22, 6443, 10250, 80, 443) on each VM's IP and show which respond — a real TCP connect per port, short timeout, run concurrently. Off by default: unlike the rest of `ls` (local state only), this does live network I/O and can add latency, especially for an unreachable/booting VM
  -o, --output <OUTPUT>  Output format: `table` (default) or `json` (ADR-0005). The `ports_open` field is included only with `--ports` (same as the table column — the probe does live network I/O, off by default) [default: table] [possible values: table, json]
  -h, --help             Print help

Usage: dlx vm status [OPTIONS] [NAME]

Arguments:
  [NAME]  VM to query (omit for the state of ALL)

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm stop [OPTIONS] <NAME>

Arguments:
  <NAME>  

Options:
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm rm [OPTIONS] <NAME>

Arguments:
  <NAME>  

Options:
  -f, --force         Remove the local state even if the libvirt cleanup fails
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help

Usage: dlx vm apply [OPTIONS]

Options:
  -f, --file <FILE>   
      --l18n <en|pt>  Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand
  -h, --help          Print help