.\" SPDX-License-Identifier: AGPL-3.0-or-later
.\" Copyright (c) 2025-2026 Cristian Cezar Moisés
.TH ZUPT-GUI 1 "2026-08-31" "ZUPT 5.2.8" "User Commands"
.SH NAME
zupt-gui \- Qt interface for the ZUPT backup utility
.SH SYNOPSIS
.B zupt-gui
.RI [ ARCHIVE.zupt ]
.br
.B zupt-gui
.BI --compress " FILE ..."
.br
.B zupt-gui
.BI --extract " ARCHIVE.zupt"
.br
.B zupt-gui
.RB [ --help | --version | --selftest ]
.SH DESCRIPTION
.B zupt-gui
is a Python Qt 6 frontend for
.BR zupt (1).
It creates, inspects, verifies, and extracts archives by running the CLI as a
child process. It can also request CLI disk backup and restore operations.
The GUI does not implement an archive codec or cryptography itself.
.PP
PySide6 is tried first and PyQt6 is used as a fallback. The selected
.B zupt
command is checked by executing
.BR "zupt version" .
The ZUPT command and environment variables are preferred; renamed-era names
are accepted only for compatibility with an existing installation.
.PP
When paired with the source-only baseline CLI, the frontend uses a build with
.B WITH_SDK=0
and
.BR WITH_PQBOX=0 .
Native password,
.B --pq
(ML-KEM-768 plus X25519), and
.B --pq-only
(ML-KEM-768) modes remain available. The GUI parses the CLI's
.B Build integrations:
line and exposes
.B --pq-sdk
or
.B --pq-box
only when libvuptsdk or libpqvaptvupt is independently reported enabled.
These two optional integrations are detected separately.
.PP
The gated 5.2.8 GUI release set is limited to the architecture-independent DEB,
noarch/source RPM, and source-only portable ZIP named in the project README.
Package gates require exact checks and installed off-screen GUI/CLI integration.
The portable ZIP receives source scans, an exact safe-member allowlist, and an
extracted launcher test; it bundles no Python, Qt, CLI, or compiled runtime.
AppImage, AppDir and Flatpak bundles and Windows/macOS GUI installers are not
promoted; the Windows ZIP and macOS DMG are CLI-only.
.PP
The GUI does not expose the CLI's recovery-only
.B --allow-legacy-no-ait
option. A known, trusted pre-AIT archive must be recovered explicitly with the
CLI; untrusted trailerless archives must remain rejected.
.SH OPTIONS
.TP
.B --compress
Open the Compress tab with the remaining arguments selected as inputs.
.TP
.B --extract
Open the Extract tab with the following archive selected.
.TP
.B --selftest
Create the complete interface, run the event loop briefly, and exit. A display
backend (or a suitable off-screen Qt backend) is still required.
.TP
.BR --version , " -V"
Print the GUI, Qt binding, CLI version, and selected CLI path.
.TP
.BR --help , " -h"
Print command-line usage.
.SH TABS
.TP
.B Keys
Generate and export recipient keys. Mode choices follow CLI capability
detection, including independent SDK and PQ-box choices when enabled.
.TP
.B Compress
Choose inputs, destination, codec options, password, and an optional recipient
public key.
.TP
.B Extract
Choose an archive, output directory, and any required password or private key.
The GUI uses
.B zupt info
to auto-detect supported archive protection modes. That framing inspection is
unauthenticated and is only a mode-selection hint; the subsequent CLI extract
or test operation performs the required AIT and content validation.
.TP
.B Verify
Inspect an archive header or run the CLI integrity test with the detected
credential type.
.TP
.B Disk
Request full-device or image backup and restore through the CLI. Raw devices
may require operating-system privileges. Restore overwrites its selected target
and requires explicit confirmation in the GUI.
.TP
.B About
Show the detected CLI version and build information.
.SH ENVIRONMENT
.TP
.B ZUPT_BIN
Absolute or executable path to the preferred
.B zupt
command. It must pass the CLI version liveness check.
.TP
.B ZUPT_DEBUG
Print command-discovery diagnostics to standard error when non-empty.
.TP
.B ZUPT_NO_XCB_FALLBACK
Disable the guarded XWayland relaunch used when a Wayland window is never
exposed.
.TP
.BR VAPTVUPT_BIN , " VAPTVUPT_DEBUG" , " VAPTVUPT_NO_XCB_FALLBACK"
Renamed-era compatibility aliases for the corresponding ZUPT variables.
New integrations should use the ZUPT names.
.SH FILES
.TP
.I /usr/bin/zupt-gui
Installed launcher.
.TP
.I /usr/lib/zupt-gui/zupt_gui.py
GUI source location used by the DEB or source installer. The noarch RPM may use
an architecture-independent shared-data directory instead.
.TP
.I /usr/share/applications/zupt-gui.desktop
Desktop entry.
.PP
Distribution packages do not install a
.B vaptvupt-gui
alias. The source installer can create one only with its explicit
.B --legacy-alias
option. The optional alias has no separate manual page.
.SH BUGS
Report reproducible issues at
.UR https://github.com/cristiancmoises/zupt/issues
the ZUPT issue tracker
.UE .
.SH AUTHOR
Cristian Cezar Moisés
.SH LICENSE
The current integrated GUI source carries AGPL-3.0-or-later notices. Published
historical revisions include MIT grants that remain applicable to the exact
material distributed under them. See
.I gui/LICENSE-GUI
and the 5.2.2 licensing erratum in
.I CHANGELOG.md
for scope and repository evidence.
.SH SEE ALSO
.BR zupt (1)