dist-installer-cli(1) -- download and import Whonix/Kicksecure VMs
=============================================

<!--
# vim: tw=75 cc=76
## ronn conversion of options description breaks lines horribly if longer
## than 75 chars.
## Copyright (C) 2025 ENCRYPTED SUPPORT LLC <adrelanos@whonix.org>
## See the file COPYING for copying conditions.
-->

## SYNOPSIS
`dist-installer-cli` [options]

## DESCRIPTION
**dist-installer-cli** is an installer that automates the download and import
of Kicksecure and Whonix VMs. It supports interfaces CLI or LXQt,
and allows users to choose their preferred hypervisor, such as KVM or VirtualBox.

## OPTIONS
Options start with one or two dashes. Both long and short options that require
arguments can be separated by either spaces or an equal sign.

If an option is specified multiple times, the last assignment takes precedence.

The guest and interface can also be set by renaming the script following the
format <guest-interface-installer>.

`-g`, `--guest`=<guest>

        Set the guest operating system. Options: kicksecure, whonix (default).

`-u`, `--guest-version`=<version>

        Specify the guest version. If none is provided, the default is to query the API.

`-i`, `--interface`=<interface>

        Define the guest interface. Options: cli, lxqt (default).

`-m`, `--hypervisor`=<hypervisor>

        Choose the hypervisor for the guest. Options: kvm, virtualbox (default).

`--oracle-repo`

        Use the Oracle repository for VirtualBox. This is the default for Fedora-based
        distributions. It's optional for Debian-based ones but may be set by developers
        in the future if the Debian repository discontinues the VirtualBox package.

`-o`, `--onion`

        Route requests through the Tor onion network whenever possible.

`-s`, `--socks-proxy`=<proxy>

        Define a TCP SOCKS proxy for requests in the format "host:addr". If not specified
        and Tor onion routing is enabled, it defaults to TOR_SOCKS_HOST:TOR_SOCKS_PORT.
        If this fails, it defaults to host 127.0.0.1 and checks for TBB on port 9151
        or the system's tor on port 9050.

`-l`, `--log-level`=<level>

        Define the logging level. Options: debug, info, notice (default), warn, error.
        Log messages below the specified level are displayed.

`-k`, `--no-boot`

        Prevent the guest from booting after the installation. By default, the installer prompts
        to start the guest. In non-interactive mode, the guest starts automatically.

`--no-import`

        Skip the importation of the guest. By default, if the guest hasn't been imported, it will be.

`--import-only`=<vm>

        Import only a specific Virtual Machine when the guest is Whonix.
        Options: gateway, workstation, both.

`--redownload`

        Force a new download even if a flag indicates a previous successful download.

`--destroy-existing-guest`

        Deletes any existing virtual machine(s) and re-imports them.
        Warning: This action poses a risk of data loss as it involves
                 a complete reinstallation of the VM(s). Proceed with caution.

`-P`, `--directory-prefix`=<directory>

        Define the absolute path directory to store downloaded files. Defaults to
        $HOME/dist-installer-cli-download. The directory must exist and be writable by the user.
        Changing this directory without moving the previously downloaded files triggers a new download.

`-n`, `--non-interactive`

        Enable non-interactive mode. In this mode, all default options are assumed,
        including accepting the license and starting the guest.

`--mirror`=<number>

        Select a mirror based on its index number. If no mirror is selected,
        the default is mirror 0 for clearnet and mirror 0 for onion.
        Mirror indices:
          0 [DE] download.whonix.org (onion available)
          1 [DK] mirrors.dotsrc.org (onion available)
          2 [HU] quantum-mirror.hu

`--virtualbox-only`

        Only download and install VirtualBox.

`--allow-errors`

        Enable dirty mode, where the program continues despite errors.

`--no-show-errors`

        Suppress error messages.

`--ci`

        Enable CI mode for testing within Continuous Integration (CI) environments.

`--testers`

        Download the tester's version.

`-D`, `--dev`

        Activate development mode, which sets the default download version to an empty image.

`-d`, `--dry-run`

        Simulate a run without executing impactful actions.

`-t`, `--getopt`

        Display parsed options and exit.

`-V`, `--version`

        Display the version number and exit.

`-h`, `--help`

        Display help for commands and exit.

## EXAMPLES

To install Whonix LXQt for KVM:

        $ dist-installer-cli --guest=whonix --interface=lxqt --hypervisor=kvm

To install the default configuration using Tor onion routing and a SOCKS proxy:

        $ dist-installer-cli --onion --socks-proxy=127.0.0.1:9050

To install the default configuration non-interactively and display info messages:

        $ dist-installer-cli --non-interactive --log-level=info

## EXIT CODES
The installer returns the exit code of the last command executed.
Some command exit codes might clash with the script's exit code, which would be considered a bug.
Exit codes for <curl> and <rsync> are reserved to avoid conflicts and simplify debugging.

    1       General error.

    2       Unrecognized option or incorrect usage.

    3-35    Rsync errors.

    3-96    Curl errors.

    100     License declined by the user.

    101     Unsupported system.

    102     Virtual machines already exist.

    103     Download failure.

    104     Digital signature verification failure.

    105     Virtual machine import failure.

    106     Failed to start virtual machines due to anticipated virtualization issues.

    107     Failed to start virtual machines due to unforeseen issues.

    108     Oracle VirtualBox package found but option `--oracle-repo` was not provided.

    109     Oracle VirtualBox installed from tarball/source, but messing with packages installed from source can have unexpected results.

## AUTHOR

This man page was authored by grass (grass@danwin1210.de).

## WWW
For more information, visit:
https://www.whonix.org/wiki/Dev/Linux_Installer

## SEE ALSO
curl(1), sha512sum(1), signify-openbsd(1), qemu(1), kvm(1)
