// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page get-and-install-qt-cli.html

    \title Get and Install Qt with Command Line Interface
    \brief How to download and install with CLI.

    From Qt Online Installer and Maintenance Tool 4.0 onward, an improved command line
    interface (CLI) enables installing, uninstalling, updating, and searching
    components. You can use the command line interface with Qt Online installer
    and Maintenance Tool.

    The command line interface supports both \b{interactive and non-interactive
    usage (unattended usage)}. The following topics provide examples and
    information on how you can use the command line interface:

    \list
        \li \l{Installing Without User Interaction}
        \li \l{Installing With User Interaction}
        \li \l{Uninstalling Packages}
        \li \l{Searching Packages}
        \li \l{Listing Installed Packages}
        \li \l{Checking Updates}
        \li \l{Updating Packages}
        \li \l{Popular Commands}
        \li \l{Selecting Mirror for Opensource}
        \li \l{Further Information}
    \endlist

    \section1 Installing Without User Interaction

    By default, Qt Online installer or Maintenance Tool may ask for
    additional information during installation, which requires user attention.
    Unattended usage via the command line interface is possible by providing all
    the requested information beforehand with appropriate options.

    \section2 New Installation with Qt Online Installer

    You can do new installations from the command line interface without user
    interaction as follows:

    \list 1
        \li Define the \e{Qt Online Installer} executable.
        \li Define the installation directory with \b{\c{--root}}.
        \li Use the \b{\c{install <list of packages>}} command with \b{options
        for unattended usage}. See the full list of options in
        \l{Options for Unattended Usage}.
    \endlist

    The following examples demonstrate how you install Qt 6.5.0 binaries
    with Qt Online installer for Windows, macOS, and Linux. The unattended
    commands automatically accept the licenses (\b{\c{--accept-licenses}}), answer
    all message queries with their default answer (\b{\c{--default-answer}}), skip
    asking for permission to continue performing (\b{\c{--confirm-command}}), and
    accept all message queries (\b{\c{accept-messages}}):

    \badcode
    # Windows: new installation with Qt Online installer
    qt-unified-windows-x64-[Qt Online Installer version]-online.exe --root C:\Users\[username]\installation_dir --accept-licenses --default-answer --confirm-command --accept-messages install qt.qt6.650.win64_msvc2019_64

    # macOS: new installation with Qt Online installer
    qt-unified-macOS-x64-[Qt Online Installer version]-online.dmg --root /home/<username>/installation_dir --accept-licenses --default-answer --confirm-command --accept-messages install qt.qt6.650.clang_644

    # linux: new installation with Qt Online installer
    qt-unified-linux-x64-[Qt Online Installer version]-online.run --root /home/<username>/installation_dir --accept-licenses --default-answer --confirm-command --accept-messages install qt.qt6.650.gcc_64
    \endcode

    \l{Options for Unattended Usage} lists all available options for unattended
    usage.

    \section2 Updating Installation with Maintenance Tool

    You can update existing installation from the command line interface without
    user interaction as follows:

    \list 1
        \li Define the \e{Maintenance Tool} executable.
        \li Use \b{\c{install <list of packages>}} with \b{options for
        unattended usage}. See the full list of options in
        \l{Options for Unattended Usage}.
    \endlist

    The following examples demonstrate how you add Qt 6.5.0 binaries
    with Maintenance Tool to an exsting installation on Windows, macOS, and
    Linux. The unattended commands automatically accept the licenses
    (\b{\c{--accept-licenses}}), answer all message queries with their default
    answer (\b{\c{--default-answer}}), skip  asking for permission to continue
    performing (\b{\c{--confirm-command}}), and accept all message queries
    \b{\c{accept-messages}}):

    \badcode
    # Windows: update installation with Maintenance Tool
    MaintenanceTool.exe --accept-licenses --default-answer --confirm-command --accept-messages install qt.qt6.650.win64_msvc2019_64

    # macOS: update installation with Maintenance Tool
    MaintenanceTool.dmg --accept-licenses --default-answer --confirm-command --accept-messages install qt.qt6.650.clang_64

    # linux: update installation with Maintenance Tool
    MaintenanceTool.run --accept-licenses --default-answer --confirm-command --accept-messages install qt.qt6.650.gcc_64
    \endcode

    \section2 Options for Unattended Usage

    The following table lists all options for unattended command line usage:

    \table
    \header
        \li Option for unattended usage
        \li Description
    \row
        \li \c{--accept-licenses}
        \li Automatically accepts all license agreements.
    \row
        \li \c{--accept-obligations}
        \li In the opensource installations, accepts Qt Open Source usage
        obligations without user input.
    \row
        \li \c{--default-answer}
        \li  Answers all message queries with their default answer.
    \row
        \li \c{--auto-answer <identifier=value>}
        \li In case you want different answers to certain queries, you can use
        this option. For example,
        \c{--auto-answer telemetry-question=Yes,AssociateCommonFiletypes=Yes}.
        See all message identifiers in \l{Message Identifiers for --auto-answer}.
    \row
        \li \c{--accept-messages}
        \li Accepts all message queries.
    \row
        \li \c{--reject-messages}
        \li Rejects all message queries.
    \row
        \li \c{--confirm-command}
        \li By default, Qt Online Installer and Maintenance Tool print a summary
        of components to be affected by the option. Then they ask for
        permission to continue acting, to prevent accidental
        changes. This option skips asking for permission to continue.
    \row
        \li \c{--email <your_email>}
        \li Provides the email when you log in from the command line. For more
        information, see \l{Providing Login Information}.
    \row
        \li \c{--pw <your_pw>}
        \li Provides the password when you log in from the command line. For
        more information, see \l{Providing Login Information}.
    \row
        \li \c{--file-query <identifier=value>}
        \li Sometimes the installer asks for a file or a folder location.
        You can provide the location with \c{--file-query <identifier=value>}.
        For example, \c{--file-query PathForSDP7=<path_to_sdp>}.

        The identifiers are printed into the command line before the actual
        question and message type. You can pick up the identifiers from there.
    \endtable

    \section2 Message Identifiers for --auto-answer

    Use the \c{--auto-answer} option to provide answers to certain queries. The
    following table lists known identifiers and values used for
    \c{--auto-answer}:

    \table
        \header
        \li ID
        \li Values
        \li Default
    \row
        \li OperationDoesNotExistError
        \li Abort, Ignore
        \li Ignore
    \row
        \li OverwriteTargetDirectory
        \li Yes, No
        \li No
    \row
        \li stopProcessesForUpdates
        \li Retry, Ignore, Cancel
        \li Cancel
    \row
        \li installationErrorWithCancel
        \li Retry, Ignore, Cancel
        \li Cancel
    \row
        \li installationErrorWithIgnore
        \li Retry, Ignore
        \li Ignore
    \row
        \li AssociateCommonFiletypes
        \li Yes, No
        \li Yes
    \row
        \li telemetry-question
        \li Yes, No
        \li Yes
    \endtable

    \section2 Providing Login Information

    Qt Online Installer and MaintenanceTool have a forced login. The forced
    login uses information on the \e{qtaccount.ini} file if it is available in
    cache. You find \e{qtaccount.ini} as follows:

    \table
    \header
        \li Host
        \li qtaccount.ini location
    \row
        \li Windows
        \li \c{C:\Users\<username>\AppData\Roaming\Qt}
    \row
        \li macOS
        \li \c{/Users/<username>/Library/Application Support/Qt/qtaccount.ini}
    \row
        \li Linux
        \li \c{/home/<username>/.local/share/Qt/qtaccount.ini}
    \endtable

    Optionally, you can login either from the command line using the switches
    for email and password: \c{--email <your_email>} and \c{--pw <your_pw>}.

    Alternatively, you can save the jwt token to the environment variable
    \c{QT_INSTALLER_JWT_TOKEN}. You find the token in the \e{qtaccount.ini} file.

    \section1 Installing With User Interaction

    You can use the command line interface with user interaction as follows:

    \list 1
        \li Define the executable:
            \list
                \li \e{Qt Online Installer} if you need to do a new installation.
                \li \e{Maintenance Tool} if you need to update an existing
                installation.
            \endlist
        \li When you do a new installation,
        define the installation directory with \c{--root}
        \li  Use \b{\c{install <list of packages>}} to install the listed
        packages.
    \endlist

    The following examples demonstrate how you create a new installation
    of Qt 6.5.0 binaries with Qt Online installer for Windows, macOS, and Linux:

    \badcode
    # Windows: new installation with user interaction
    qt-unified-windows-x64-[Qt Online Installer version]-online.exe --root C:\Users\[username]\installation_dir install qt.qt6.650.win64_msvc2019_64

    # macOS: new installation with user interaction
    qt-unified-macOS-x64-[Qt Online Installer version]-online.dmg --root /home/<username>/installation_dir install qt.qt6.650.clang_64

    # linux: new installation with user interaction
    qt-unified-linux-x64-[Qt Online Installer version]-online.run --root /home/<username>/installation_dir install qt.qt6.650.gcc_64
    \endcode

    The following examples demonstrate how you update your existing
    installation by installing the Qt 6.5.0 binaries with Maintenance Tool:

    \badcode
    # Windows: update installation with Maintenance Tool
    MaintenanceTool.exe install qt.qt6.650.win64_msvc2019_64

    # macOS: update installation with Maintenance Tool
    MaintenanceTool.dmg install qt.qt6.650.clang_64

    # Linux: update installation with Maintenance Tool
    MaintenanceTool.run install qt.qt6.650.gcc_64
    \endcode

    \section1 Uninstalling Packages

    The command line interface provides two commands for uninstalling packages:

    \list
        \li The \b{\c{remove <list of packages>}} command uninstalls the listed
        packages.
        \li The \b{\c{purge}} command uninstalls all installed packages.
    \endlist

    You should use both commands with Maintenance Tool.

    By default, Maintenance Tool prints a summary of components to be affected
    by the command. Then the tool asks for permission to continue acting, to
    prevent accidental changes. Use \b{\c{--confirm-command}} to skip asking for
    permission to continue.

    The following example uninstalls the Qt 6.5.0 binaries without user
    interaction:

    \badcode
    # windows
    MaintenanceTool.exe --confirm-command remove qt.qt6.650.win64_msvc2019_64

    # macOS
    MaintenanceTool.dmg --confirm-command remove install qt.qt6.650.clang_64

    # linux
    MaintenanceTool.run --confirm-command remove qt.qt6.650.gcc_64
    \endcode

    The following examples uninstall all packages and ask for permission to
    continue performing the action:

    \badcode
    # Windows
    MaintenanceTool.exe purge

    # macOS
    MaintenanceTool.dmg purge

    # Linux
    MaintenanceTool.run purge
    \endcode

    \section1 Searching Packages

    Search available packages with the \c{search} command and regular
    expressions: \b{\c{search <regexp>}}. You can filter the results with
    \b{\c{--filter-packages <regexp>}}. For example, filtering with the display
    name information can help search.

    For example, the following command finds all MSVC 2019 packages for Qt 6.5.0:

    \badcode
    search .*650.*msvc2019
    \endcode

    You get the same result when you filter the search result as follows:

    \badcode
    search --filter-packages DisplayName=MSVC 2019,Version=6.5.0
    \endcode

    As a result, you get the following packages:

    \badcode
    <availablepackages>
        <package name="qt.qt6.650.win64_msvc2019_64" displayname="MSVC 2019 64-bit" version="6.5.0-0-202303290841"/>
        <package name="qt.qt6.650.win64_msvc2019_arm64" displayname="MSVC 2019 ARM64 (TP)" version="6.5.0-0-202303290841"/>
    </availablepackages>
    \endcode

    You can also use filtering when you search all Qt versions that some package
    is provided for. For example, search all Qt Charts packages provided for
    Qt versions:

    \badcode
    search --filter-packages DisplayName=charts
    \endcode

    The search result is as follows:

    \badcode
    <availablepackages>
        <package name="qt.qt5.5125.qtcharts" displayname="Qt Charts" version="5.12.5-0-201909090651"/>
        <package name="qt.qt6.641.addons.qtcharts" displayname="Qt Charts" version="6.4.1-0-202211101525"/>
        <package name="qt.qt5.5123.qtcharts" displayname="Qt Charts" version="5.12.3-0-201904161619"/>
    \endcode

    \section1 Listing Installed Packages

    The \b{\c{list}} command lists all packages you have installed. Use the
    command with Maintenance Tool as follows:

    \badcode
    # Windows
    MaintenanceTool.exe list

    # macOS
    MaintenanceTool.dmg list

    # Linux
    MaintenanceTool.run list
    \endcode

    \section1 Checking Updates

    The \b{\c{check-updates}} command checks the updates that are available for
    the installed packages. Use the command with Maintenance Tool as follows:

    \badcode
    # Windows
    MaintenanceTool.exe check-updates

    # macOS
    MaintenanceTool.dmg check-updates

    # Linux
    MaintenanceTool.run check-updates

    \endcode

    \section1 Updating Packages

    The \b{\c{ update}} command updates the installed packages. Use the command
    with Maintenance Tool as follows:

    \badcode
    # windows
    MaintenanceTool.exe update

    # macOS
    MaintenanceTool.dmg update

    # linux
    MaintenanceTool.run update
    \endcode

    \section1 Popular Commands

    Use the command \b{\c{<installer_executable> --help}} to study the available
    commands and options. Popular commands are as follows:

    \table
    \header
        \li Command
        \li Usage
    \row
        \li \c{in}, \c{install <pkg ...>}
        \li Installs packages given as an argument. If you don't give any
        packages, installs the default package set.
    \row
        \li \c{rm}, \c{remove <pkg ...>}
        \li Uninstalls selected packages and their child components.
    \row
        \li \c{ch}, \c{check-updates}
        \li Shows information about available updates on Maintenance Tool.
    \row
        \li \c{up}, \c{update <pkg ...>}
        \li Updates packages given as an argument. If no packages are given,
        install all available updates.
    \row
        \li \c{se}, \c{search <regexp>}
        \li Searches available packages. If you don't give any search pattern,
        shows all available packages.
        You can use the \c{--filter-packages} option to specify additional
        filters for the search operation. See
        \l{https://doc.qt.io/qtinstallerframework/ifw-cli.html#summary-of-options}{Summary of Options}
        in Qt Installer Framework Manual.
    \endtable

    \l{https://doc.qt.io/qtinstallerframework/ifw-cli.html}{Qt Installer Framework Manual}
    provides more information about the commands and options.

    \section1 Selecting Mirror for Opensource

    The Qt Online Installer has an option for selecting a mirror for opensource
    metadata and downloads. Set the mirror from the command line with the
    \b{\c{--mirror}} option.

    For example, use \c{--mirror} as follows:

    \badcode
    installer(.exe) --mirror http://www.nic.funet.fi/pub/mirrors/download.qt-project.org
    installer(.exe) --mirror http://ftp2.nluug.nl/languages/qt
    maintenancetool(.exe) --mirror http://qt.mirror.constant.com
    \endcode

    As the example shows, don't use the full path but use the path before
    '/online' (no forward slash at the end).

    You find the available mirrors from
    \l{https://download.qt.io/online/qtsdkrepository/windows_x86/root/qt/Updates.xml.mirrorlist}.

    \section1 Further Information

    \l{https://doc.qt.io/qtinstallerframework/}{Qt Installer Framework Manual}
    provides more detailed information about the command line interface:

    \list
        \li \l{https://doc.qt.io/qtinstallerframework/ifw-use-cases-cli.html}{Using from Command Line}
        describes different command line interface use cases.
        \li \l{https://doc.qt.io/qtinstallerframework/ifw-cli.html#summary-of-options}{Summary of Options}
        lists all available options.
        \li \l{https://doc.qt.io/qtinstallerframework/ifw-cli.html#summary-of-commands}{Summary of Commands}
        lists all available commands.
    \endlist
*/
