From c6d8b2ecbfe1581e0b6c052d41483e3135800c3c Mon Sep 17 00:00:00 2001 From: Gabriel Dufresne Date: Tue, 1 Sep 2026 08:58:11 -0400 Subject: [PATCH 1/5] Document portable mode and fill gaps in the CLI reference --- README.md | 18 +++++++- docs/CLI.md | 60 +++++++++++++++++++++++---- docs/PORTABLE.md | 106 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 173 insertions(+), 11 deletions(-) create mode 100644 docs/PORTABLE.md diff --git a/README.md b/README.md index 31cc3f05b2..b96d2b6a7a 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,7 @@ Read more in the [Devolutions announcement](https://devolutions.net/blog/2026/03 - [Frequently Asked Questions](#frequently-asked-questions) - [CLI reference](docs/CLI.md) - [IPC reference](docs/IPC.md) + - [Portable mode](docs/PORTABLE.md) ## Installation

There are multiple ways to install UniGetUI — choose whichever one you prefer!

@@ -138,6 +139,11 @@ tar -xzf UniGetUI.linux-x64.tar.gz Replace `x64` with `arm64` in the file name when using the arm64 build. +### Portable installations + +The `.zip` and `.tar.gz` downloads are portable in the sense that they need no installer, but they still store settings in your user profile. To make UniGetUI keep its data alongside the executable — and for the Windows installer's portable installation type — see [portable mode](docs/PORTABLE.md). + + ## Update UniGetUI UniGetUI has a built-in autoupdater. On Windows, it can also be updated like any other package within UniGetUI when installed through WinGet, Scoop, or Chocolatey. @@ -149,12 +155,18 @@ UniGetUI has a built-in autoupdater. On Windows, it can also be updated like any - Discover new packages and filter them to easily find the package you want. - View detailed metadata about any package before installing it. Get the direct download URL or the name of the publisher, as well as the size of the download. - Easily bulk-install, update, or uninstall multiple packages at once selecting multiple packages before performing an operation - - Automatically update packages, or be notified when updates become available. Skip versions or completely ignore updates on a per-package basis. + - Automatically update packages, or be notified when updates become available. Skip versions or completely ignore updates on a per-package basis, or restrict automatic updating to a hand-picked set of packages. + - Schedule maintenance: run update checks, install updates, and take local or cloud backups at app start, after every update check, on an interval, or daily/weekly at a chosen time. - The system tray icon will also show the available updates and installed packages where supported, to efficiently update a program or remove a package from your system. - Easily customize how and where packages are installed. Select different installation options and switches for each package. Install an older version or force a specific architecture where supported. \[But don't worry, those options will be saved for future updates for this package*] - Share packages with your friends using generated package links. - Export custom lists of packages to then import them to another machine and install those packages with previously specified, custom installation parameters. Setting up machines or configuring a specific software setup has never been easier. - - Backup your packages to a local file to easily recover your setup in a matter of seconds when migrating to a new machine* + - Backup your packages to a local file to easily recover your setup in a matter of seconds when migrating to a new machine*, keeping only the most recent backups so the folder does not grow without bound. + - Sync those backups to a secret GitHub Gist, so a new machine can restore your package list after a single sign-in. + - Review every past operation in the operation history, with the full log of each one kept for troubleshooting. + - On Windows, decide which desktop and Start Menu shortcuts installers are allowed to create, and pin a package's shortcuts to a Start Menu folder of your choosing — both re-applied on every upgrade. + - Drive the whole application from the command line, or from scripts through its local automation API. See the [CLI reference](docs/CLI.md) and the [IPC reference](docs/IPC.md). + - Run UniGetUI as a portable app that keeps its settings next to the executable. See the [portable mode reference](docs/PORTABLE.md). ## Package Managers @@ -240,3 +252,5 @@ Some package managers and repositories implement checks to mitigate the risks of ## Command-line interface: Check out the CLI reference [here](docs/CLI.md) and the IPC reference [here](docs/IPC.md). + +For portable installations and where UniGetUI keeps its data, see the [portable mode reference](docs/PORTABLE.md). diff --git a/docs/CLI.md b/docs/CLI.md index 701af6b89f..4a2ab6a576 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -3,6 +3,7 @@ This file documents the **public command-line surface** exposed by UniGetUI in the 2026 CLI redesign. - For the background IPC API that powers these commands, see [IPC.md](IPC.md). +- For portable installations and where UniGetUI stores its data, see [PORTABLE.md](PORTABLE.md). - For developer-only Avalonia diagnostics toggles, see the project source and build props; they are intentionally not documented here as public CLI arguments. ## Quick start @@ -45,10 +46,13 @@ Related environment variables: ## Command grammar notes -- Command nouns accept singular or plural forms: `operation`/`operations`, `package`/`packages`, `manager`/`managers`, and so on. +- Command nouns accept singular or plural forms: `operation`/`operations`, `package`/`packages`, `manager`/`managers`, `source`/`sources`, `shortcut`/`shortcuts`, `log`/`logs`, `backup`/`backups`, and `bundle`/`bundles`. +- `startmenu` is accepted as a spelling of `start-menu`, and `folders` as a spelling of `folder`. - Compatibility aliases are accepted for some flags: - `--id` maps to `--package-id` or `--operation-id` where appropriate - `--source` maps to `--package-source` + - `--source-name` and `--source-url` map to `--name` and `--url` on `source add` and `source remove` + - `--name` maps to `--key` on `backup cloud download` and `backup cloud restore` - Boolean options use explicit values such as `--enabled true` or `--wait false`. - `--detach` is shorthand for asynchronous package operations (`--wait false`). - `--manager` uses stable manager ids, not GUI labels. Current ids: `apt`, `bun`, `cargo`, `chocolatey`, `dnf`, `dotnet-tool`, `flatpak`, `homebrew`, `npm`, `pacman`, `pip`, `pwsh`, `scoop`, `snap`, `vcpkg`, `winget`, and `winps`. @@ -134,6 +138,29 @@ Available keys live in: | `shortcut reset` | `--path ` | None | Clears the stored verdict for one shortcut. | | `shortcut reset-all` | None | None | Clears all stored shortcut verdicts. | +### Start Menu shortcuts + +Windows only. Deletion verdicts are keyed by shortcut path and are re-applied whenever an upgrade recreates the shortcut. Paths outside a Start Menu `Programs` directory, and paths that are not a `.lnk` or `.url` shortcut, are rejected. + +| Command | Required options | Optional options | Notes | +| --- | --- | --- | --- | +| `start-menu shortcut list` | None | None | Lists tracked Start Menu shortcuts and stored keep/delete verdicts. | +| `start-menu shortcut set` | `--path `, `--status ` | None | Marks a Start Menu shortcut to keep or delete. | +| `start-menu shortcut reset` | `--path ` | None | Clears the stored verdict for one shortcut. | +| `start-menu shortcut reset-all` | None | None | Clears every stored verdict. Folder rules and the relocations they recorded are left alone. | + +### Start Menu folders + +Windows only. A folder rule names the subfolder of the current user's Start Menu `Programs` directory where a package should keep its shortcuts. UniGetUI re-applies it after every install and upgrade, and deletes the relocated shortcuts when the package is uninstalled. + +`--package` is the package identity in `manager\PackageId` form, for example `winget\Python.Python.3.13`; the manager segment is lower-cased. `--folder` must be a subfolder of the Start Menu `Programs` directory, so an absolute path, a `..` segment or the machine-wide directory is rejected. + +| Command | Required options | Optional options | Notes | +| --- | --- | --- | --- | +| `start-menu folder list` | None | None | Lists the stored folder rules. | +| `start-menu folder set` | `--package `, `--folder ` | `--relocate-existing` | Stores a folder rule. `--relocate-existing` also moves the shortcuts that already match the package. | +| `start-menu folder remove` | `--package ` | None | Removes the folder rule for one package. | + ### Logs | Command | Required options | Optional options | Notes | @@ -219,10 +246,9 @@ These parameters are accepted by the app executables in addition to the automati | Parameter | Meaning | Notes | | --- | --- | --- | | `--daemon` | Starts UniGetUI minimized to the notification area. | Requires the corresponding startup setting. | -| `--welcome` | Opens the setup wizard. | Historical compatibility flag. | | `--updateapps` | Forces automatic installation of available updates. | Historical compatibility flag. | -| `--report-all-errors` | Opens the error report page for any crash while loading. | Troubleshooting flag. | | `--uninstall-unigetui` | Unregisters UniGetUI from the notification panel and quits. | Historical; only valid for specific old versions. | +| `--uninstall-wingetui` | Unregisters the legacy WingetUI install from the notification panel and quits. | Historical; used by the WingetUI uninstaller. | | `--migrate-wingetui-to-unigetui` | Migrates legacy WingetUI data and shortcuts, then quits. | Migration helper. | | `--help` / `-h` | Prints CLI help. | For the direct verb-based CLI. | | `--import-settings ` | Imports settings from a JSON file. | Existing settings are replaced. | @@ -234,17 +260,31 @@ These parameters are accepted by the app executables in addition to the automati | `--enable-secure-setting-for-user ` / `--disable-secure-setting-for-user ` | Toggles one secure setting for a specified user. | May require elevation. | | `` | Loads a valid bundle file into the Package Bundles page. | Supported extensions include `.ubundle`, `.json`, `.yaml`, and `.xml`. | +## Other environment variables + +These are read by the application itself rather than by the CLI client. + +| Variable | Values | Meaning | +| --- | --- | --- | +| `UNIGETUI_WINGET_CLI` | `default`, `winget`, `pinget` | Chooses which WinGet command-line tool the WinGet manager drives. Takes precedence over the `WinGetCliToolPreference` setting. | +| `UNIGETUI_WINGET_COM` | `default`, `enabled`/`enable`/`on`/`true`/`1`, `disabled`/`disable`/`off`/`false`/`0` | Forces the WinGet COM API on or off instead of letting UniGetUI decide. Takes precedence over the `WinGetComApiPolicy` setting. | +| `UNIGETUI_FONT_FAMILY` | A font family name | Windows only. Prepends a family to the UI font chain. Ignored when the "use the system UI font" setting is on, and an entry containing the Avalonia `$Default` family is discarded. | +| `UNIGETUI_FORCE_NATIVE_LINUX_DECORATIONS` | `1`/`true`/`on`/`yes`/`enabled`, `0`/`false`/`off`/`no`/`disabled` | Linux only. Forces the window manager's own title bar on or off instead of auto-detecting. An unrecognized value is ignored with a warning. | +| `UNIGETUI_GITHUB_TOKEN_NAMESPACE` | Any string | Suffixes the credential-store entry holding the GitHub backup token, so several UniGetUI instances on one machine can hold separate logins. | +| `WEBVIEW2_BROWSER_EXECUTABLE_FOLDER` | A directory path | Windows only. Points the embedded web view at a fixed-version WebView2 runtime instead of the installed evergreen one. | + ## Deep links -UniGetUI also accepts the following `unigetui://` links: +The Windows installer registers a `unigetui://` protocol handler for regular installations; a portable install does not register it, see [PORTABLE.md](PORTABLE.md). It is used to route notification clicks back into a running instance, and accepts these actions: | Deep link | Meaning | | --- | --- | -| `unigetui://showPackage?id={id}&managerName={manager}&sourceName={source}` | Opens package details for the specified package. | -| `unigetui://showUniGetUI` | Shows UniGetUI and brings the window to the front. | -| `unigetui://showDiscoverPage` | Opens the Discover page. | -| `unigetui://showUpdatesPage` | Opens the Updates page. | -| `unigetui://showInstalledPage` | Opens the Installed page. | +| `unigetui://openUniGetUI` | Shows UniGetUI and brings the window to the front. | +| `unigetui://openUniGetUIOnUpdatesTab` | Shows UniGetUI on the Software Updates page. | +| `unigetui://updateAll` | Starts an update for every available package update. | +| `unigetui://releaseSelfUpdateLock` | Allows a pending UniGetUI self-update to proceed. | + +Anything else after `unigetui://` is ignored. The action is only dispatched when UniGetUI is already running: a link that cold-starts the app launches it normally and the action is dropped. To drive UniGetUI programmatically, use the verb commands above or the [IPC API](IPC.md) rather than deep links. ## Installer parameters @@ -260,3 +300,5 @@ The installer is Inno Setup based. It supports the standard [Inno Setup command- | `/EnableSystemChocolatey` | Deprecated no-op kept for compatibility. | | `/NoWinGet` | Do not install WinGet and Microsoft.WinGet.Client if they are missing. | | `/MSStore` | Microsoft Store install mode: skip the MSVC and WebView2 dependency installers, do not launch UniGetUI after installation, and disable startup at login. Use with `/CURRENTUSER` to select user-local scope. | + +The installation type is an Inno Setup task rather than a switch. Pass `/TASKS="portableinstall"` for a portable installation; the default is `regularinstall`, which additionally accepts `regularinstall\startmenuicon` and `regularinstall\desktopicon`. A portable install keeps its settings beside the executable and registers no protocol handler, file association, shortcuts or startup entry, see [PORTABLE.md](PORTABLE.md). diff --git a/docs/PORTABLE.md b/docs/PORTABLE.md new file mode 100644 index 0000000000..24a725bf1a --- /dev/null +++ b/docs/PORTABLE.md @@ -0,0 +1,106 @@ +# UniGetUI portable mode + +This file documents **portable installations**, which keep UniGetUI's data beside the executable. + +- For the public command-line interface, see [CLI.md](CLI.md). +- For the background IPC API, see [IPC.md](IPC.md). + +By default UniGetUI keeps its configuration, caches and package metadata in a per-user directory +outside the installation folder. Portable mode moves all of that next to the executable, so the +whole application, settings included, can live on a removable drive or be copied between +machines. + +## Enabling portable mode + +Portable mode is controlled by a single marker file named `ForceUniGetUIPortable`, placed in +the installation root next to the UniGetUI executable. The file's contents are ignored (the +one shipped by the installer is empty); only its presence matters. + +### With the Windows installer + +The installer offers “Perform a portable installation” as an installation type. Selecting +it copies the marker into the install directory. To choose it from a silent install, use Inno +Setup's standard `/TASKS` switch: + +```powershell +UniGetUI.Installer.exe /VERYSILENT /TASKS="portableinstall" +``` + +`portableinstall` and `regularinstall` are mutually exclusive; `regularinstall` is the default. + +### By hand + +Create an empty file called `ForceUniGetUIPortable` (no extension) beside the executable: + +```powershell +# Windows +New-Item -ItemType File -Path "C:\Path\To\UniGetUI\ForceUniGetUIPortable" +``` + +```bash +# macOS / Linux +touch /path/to/unigetui/ForceUniGetUIPortable +``` + +This is how you make the portable `.zip` and `.tar.gz` release archives actually portable. +They ship **without** the marker, so out of the box they still write to the per-user data +directory like a regular install. + +### Where the marker goes + +The marker is looked up in the installation root, which is normally the directory holding +the executable. When the executable sits in an `Avalonia` subdirectory of a recognizable +install root, the parent directory is used instead, so the marker belongs one level up +alongside `UniGetUI.exe` and `IntegrityTree.json`. + +On macOS the executable lives inside the `.app` bundle, so a marker placed there is discarded +whenever the bundle is replaced by an update. Re-create it after upgrading. + +## What changes + +| Data | Regular install | Portable install | +| --- | --- | --- | +| Root data directory | `%LOCALAPPDATA%\UniGetUI` on Windows; `$XDG_DATA_HOME/UniGetUI`, else `~/.local/share/UniGetUI`, on macOS and Linux | `\Settings` | +| Configuration | `\Configuration` | `\Settings\Configuration` | +| Per-package install options | `\InstallationOptions` | `\Settings\InstallationOptions` | +| Cached package metadata | `\CachedMetadata` | `\Settings\CachedMetadata` | +| Cached icons and screenshots | `\CachedMedia` | `\Settings\CachedMedia` | +| Cached language files | `\CachedLanguageFiles` | `\Settings\CachedLanguageFiles` | +| Default package-backup folder | `Documents\UniGetUI` | `Documents\UniGetUI` (**not** relocated) | + +Package backups are the one exception: their default location stays in the user's Documents +folder, and portable mode does not move it. Point it somewhere inside the portable folder from +the Backup settings page if you want backups to travel with the app. + +Portable mode also does not relocate anything owned by the package managers themselves. WinGet, +Scoop, Chocolatey, npm and the rest keep their own state in their usual per-user or system +locations, and the packages they install are installed normally. + +## What a portable install does not register + +The Windows installer registers these only for a regular installation, so a portable install +gets none of them: + +| Feature | Consequence when portable | +| --- | --- | +| `unigetui://` protocol handler | Deep links and notification-click actions are not routed by the shell. | +| `.ubundle` file association | Bundle files do not open in UniGetUI on double-click. Pass the path on the command line instead. | +| Start-at-login entry | UniGetUI does not start with Windows, and `--daemon` is not registered. | +| Start menu and desktop shortcuts | Not created. | + +## Fallback when the folder is not writable + +On first use of the data directory, UniGetUI verifies it can create and write inside +`\Settings`. If that fails, for instance on an install under `Program Files`, a +read-only volume, or a locked-down drive, portable mode is **silently abandoned for that +session** and the normal per-user directory is used instead. The reason is recorded in the +**UniGetUI Log** (sidebar menu) as “Could not access/write path”. + +Install to a location the running user can write, such as a removable drive or a folder under +the user profile, if you rely on portable mode. + +## Turning portable mode off + +Delete the `ForceUniGetUIPortable` file and restart UniGetUI. The app reverts to the per-user +data directory; the `Settings` folder is left on disk untouched, so copy anything you want to +keep out of it first. The check runs once per session, so a restart is required either way. From 08ad3533d0e43505d2be7d801eb6f2a056feba14 Mon Sep 17 00:00:00 2001 From: Gabriel Dufresne Date: Tue, 1 Sep 2026 09:11:24 -0400 Subject: [PATCH 2/5] Address review feedback on the documentation --- README.md | 4 ++-- docs/CLI.md | 4 ++-- docs/PORTABLE.md | 17 +++++++++++++---- 3 files changed, 17 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index b96d2b6a7a..3602b55d76 100644 --- a/README.md +++ b/README.md @@ -156,12 +156,12 @@ UniGetUI has a built-in autoupdater. On Windows, it can also be updated like any - View detailed metadata about any package before installing it. Get the direct download URL or the name of the publisher, as well as the size of the download. - Easily bulk-install, update, or uninstall multiple packages at once selecting multiple packages before performing an operation - Automatically update packages, or be notified when updates become available. Skip versions or completely ignore updates on a per-package basis, or restrict automatic updating to a hand-picked set of packages. - - Schedule maintenance: run update checks, install updates, and take local or cloud backups at app start, after every update check, on an interval, or daily/weekly at a chosen time. + - Schedule maintenance, with the triggers each task supports: update checks on an interval or daily/weekly at a chosen time, update installation after every update check or daily/weekly, and local or cloud backups at app start or daily/weekly. - The system tray icon will also show the available updates and installed packages where supported, to efficiently update a program or remove a package from your system. - Easily customize how and where packages are installed. Select different installation options and switches for each package. Install an older version or force a specific architecture where supported. \[But don't worry, those options will be saved for future updates for this package*] - Share packages with your friends using generated package links. - Export custom lists of packages to then import them to another machine and install those packages with previously specified, custom installation parameters. Setting up machines or configuring a specific software setup has never been easier. - - Backup your packages to a local file to easily recover your setup in a matter of seconds when migrating to a new machine*, keeping only the most recent backups so the folder does not grow without bound. + - Backup your packages to a local file to easily recover your setup in a matter of seconds when migrating to a new machine*. Every backup is kept by default; turn on timestamped file names and pick a retention limit to keep only the most recent ones. - Sync those backups to a secret GitHub Gist, so a new machine can restore your package list after a single sign-in. - Review every past operation in the operation history, with the full log of each one kept for troubleshooting. - On Windows, decide which desktop and Start Menu shortcuts installers are allowed to create, and pin a package's shortcuts to a Start Menu folder of your choosing — both re-applied on every upgrade. diff --git a/docs/CLI.md b/docs/CLI.md index 4a2ab6a576..ab0204cac2 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -153,11 +153,11 @@ Windows only. Deletion verdicts are keyed by shortcut path and are re-applied wh Windows only. A folder rule names the subfolder of the current user's Start Menu `Programs` directory where a package should keep its shortcuts. UniGetUI re-applies it after every install and upgrade, and deletes the relocated shortcuts when the package is uninstalled. -`--package` is the package identity in `manager\PackageId` form, for example `winget\Python.Python.3.13`; the manager segment is lower-cased. `--folder` must be a subfolder of the Start Menu `Programs` directory, so an absolute path, a `..` segment or the machine-wide directory is rejected. +`--package` is the rule key, in `manager\PackageId` form, for example `winget\Python.Python.3.13`; the manager segment is lower-cased. Note that the key carries no source, unlike package equivalence elsewhere in UniGetUI, so two packages sharing a manager and an id but coming from different sources share a single rule and cannot be placed in different folders. `--folder` must be a subfolder of the Start Menu `Programs` directory, so an absolute path, a `..` segment or the machine-wide directory is rejected. | Command | Required options | Optional options | Notes | | --- | --- | --- | --- | -| `start-menu folder list` | None | None | Lists the stored folder rules. | +| `start-menu folder list` | None | None | Lists the stored folder rules, plus any package that only has pending shortcuts. The latter are reported with an empty folder, so a script that wants actual rules has to skip them. | | `start-menu folder set` | `--package `, `--folder ` | `--relocate-existing` | Stores a folder rule. `--relocate-existing` also moves the shortcuts that already match the package. | | `start-menu folder remove` | `--package ` | None | Removes the folder rule for one package. | diff --git a/docs/PORTABLE.md b/docs/PORTABLE.md index 24a725bf1a..ed0bd664ba 100644 --- a/docs/PORTABLE.md +++ b/docs/PORTABLE.md @@ -8,7 +8,7 @@ This file documents **portable installations**, which keep UniGetUI's data besid By default UniGetUI keeps its configuration, caches and package metadata in a per-user directory outside the installation folder. Portable mode moves all of that next to the executable, so the whole application, settings included, can live on a removable drive or be copied between -machines. +machines. A few things deliberately stay outside that folder; see [What changes](#what-changes). ## Enabling portable mode @@ -60,18 +60,26 @@ whenever the bundle is replaced by an update. Re-create it after upgrading. | Data | Regular install | Portable install | | --- | --- | --- | -| Root data directory | `%LOCALAPPDATA%\UniGetUI` on Windows; `$XDG_DATA_HOME/UniGetUI`, else `~/.local/share/UniGetUI`, on macOS and Linux | `\Settings` | +| Root data directory | `%LOCALAPPDATA%\UniGetUI` on Windows; `~/Library/Application Support/UniGetUI` on macOS; `$XDG_DATA_HOME/UniGetUI`, else `~/.local/share/UniGetUI`, on Linux | `\Settings` | | Configuration | `\Configuration` | `\Settings\Configuration` | | Per-package install options | `\InstallationOptions` | `\Settings\InstallationOptions` | | Cached package metadata | `\CachedMetadata` | `\Settings\CachedMetadata` | | Cached icons and screenshots | `\CachedMedia` | `\Settings\CachedMedia` | | Cached language files | `\CachedLanguageFiles` | `\Settings\CachedLanguageFiles` | +| Stored secrets, macOS and Linux | `/SecureStorage` | `/Settings/SecureStorage` | +| Stored secrets, Windows | Credential Manager | Credential Manager (**not** relocated) | | Default package-backup folder | `Documents\UniGetUI` | `Documents\UniGetUI` (**not** relocated) | -Package backups are the one exception: their default location stays in the user's Documents +Package backups are one exception: their default location stays in the user's Documents folder, and portable mode does not move it. Point it somewhere inside the portable folder from the Backup settings page if you want backups to travel with the app. +The GitHub backup token is the other exception, and where it lives depends on the platform. On +macOS and Linux it is written to `SecureStorage` inside the data directory, so it travels with a +portable folder, as a plain file on disk. On Windows it is held in Credential Manager instead, +so a portable copy does not carry the login, and every portable copy on one machine shares +the same stored token unless `UNIGETUI_GITHUB_TOKEN_NAMESPACE` is set to separate them. + Portable mode also does not relocate anything owned by the package managers themselves. WinGet, Scoop, Chocolatey, npm and the rest keep their own state in their usual per-user or system locations, and the packages they install are installed normally. @@ -94,7 +102,8 @@ On first use of the data directory, UniGetUI verifies it can create and write in `\Settings`. If that fails, for instance on an install under `Program Files`, a read-only volume, or a locked-down drive, portable mode is **silently abandoned for that session** and the normal per-user directory is used instead. The reason is recorded in the -**UniGetUI Log** (sidebar menu) as “Could not access/write path”. +**UniGetUI Log** (sidebar menu) as “Could not acces/write path”, spelled with one “s” +in the message itself. Install to a location the running user can write, such as a removable drive or a folder under the user profile, if you rely on portable mode. From afc706839fe406f8e4444efc746e5ab1c09f48b3 Mon Sep 17 00:00:00 2001 From: Gabriel Dufresne <78387669+GabrielDuf@users.noreply.github.com> Date: Tue, 1 Sep 2026 09:25:16 -0400 Subject: [PATCH 3/5] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3602b55d76..ac0ec493d7 100644 --- a/README.md +++ b/README.md @@ -161,7 +161,7 @@ UniGetUI has a built-in autoupdater. On Windows, it can also be updated like any - Easily customize how and where packages are installed. Select different installation options and switches for each package. Install an older version or force a specific architecture where supported. \[But don't worry, those options will be saved for future updates for this package*] - Share packages with your friends using generated package links. - Export custom lists of packages to then import them to another machine and install those packages with previously specified, custom installation parameters. Setting up machines or configuring a specific software setup has never been easier. - - Backup your packages to a local file to easily recover your setup in a matter of seconds when migrating to a new machine*. Every backup is kept by default; turn on timestamped file names and pick a retention limit to keep only the most recent ones. + - Backup your packages to a local file to easily recover your setup in a matter of seconds when migrating to a new machine*. By default, each backup overwrites the previous file; enable timestamped file names to keep separate backups, and optionally choose a retention limit to keep only the most recent ones. - Sync those backups to a secret GitHub Gist, so a new machine can restore your package list after a single sign-in. - Review every past operation in the operation history, with the full log of each one kept for troubleshooting. - On Windows, decide which desktop and Start Menu shortcuts installers are allowed to create, and pin a package's shortcuts to a Start Menu folder of your choosing — both re-applied on every upgrade. From 1314565274daa50aa1a0210a8ffb6073a00c992c Mon Sep 17 00:00:00 2001 From: Gabriel Dufresne <78387669+GabrielDuf@users.noreply.github.com> Date: Tue, 1 Sep 2026 09:31:01 -0400 Subject: [PATCH 4/5] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ac0ec493d7..963a46961f 100644 --- a/README.md +++ b/README.md @@ -163,7 +163,7 @@ UniGetUI has a built-in autoupdater. On Windows, it can also be updated like any - Export custom lists of packages to then import them to another machine and install those packages with previously specified, custom installation parameters. Setting up machines or configuring a specific software setup has never been easier. - Backup your packages to a local file to easily recover your setup in a matter of seconds when migrating to a new machine*. By default, each backup overwrites the previous file; enable timestamped file names to keep separate backups, and optionally choose a retention limit to keep only the most recent ones. - Sync those backups to a secret GitHub Gist, so a new machine can restore your package list after a single sign-in. - - Review every past operation in the operation history, with the full log of each one kept for troubleshooting. +- Review the 1,000 most recent operations in the operation history, with up to 5,000 log lines per operation kept for troubleshooting. - On Windows, decide which desktop and Start Menu shortcuts installers are allowed to create, and pin a package's shortcuts to a Start Menu folder of your choosing — both re-applied on every upgrade. - Drive the whole application from the command line, or from scripts through its local automation API. See the [CLI reference](docs/CLI.md) and the [IPC reference](docs/IPC.md). - Run UniGetUI as a portable app that keeps its settings next to the executable. See the [portable mode reference](docs/PORTABLE.md). From e82dd03cee4dc497631b5dd45db7027019869a6f Mon Sep 17 00:00:00 2001 From: Gabriel Dufresne Date: Tue, 1 Sep 2026 09:35:33 -0400 Subject: [PATCH 5/5] Give the portable silent-install example a writable /DIR --- docs/PORTABLE.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/PORTABLE.md b/docs/PORTABLE.md index ed0bd664ba..a59ce1dd5c 100644 --- a/docs/PORTABLE.md +++ b/docs/PORTABLE.md @@ -20,14 +20,22 @@ one shipped by the installer is empty); only its presence matters. The installer offers “Perform a portable installation” as an installation type. Selecting it copies the marker into the install directory. To choose it from a silent install, use Inno -Setup's standard `/TASKS` switch: +Setup's standard `/TASKS` switch, and point `/DIR` at the location the portable copy should +live in: ```powershell -UniGetUI.Installer.exe /VERYSILENT /TASKS="portableinstall" +UniGetUI.Installer.exe /VERYSILENT /TASKS="portableinstall" /DIR="E:\UniGetUI" ``` `portableinstall` and `regularinstall` are mutually exclusive; `regularinstall` is the default. +The install directory has to be writable by the account that runs UniGetUI, or portable mode +silently falls back, as [described below](#fallback-when-the-folder-is-not-writable). The +installer defaults to per-user mode (`PrivilegesRequired=lowest`), so without `/DIR` it lands +in `%LOCALAPPDATA%\Programs\UniGetUI`, which is writable and works. An all-users install, chosen +in the dialog or with `/ALLUSERS`, lands in `C:\Program Files\UniGetUI` instead, where a +normally launched UniGetUI cannot create `Settings`. + ### By hand Create an empty file called `ForceUniGetUIPortable` (no extension) beside the executable: