|
| 1 | +# UniGetUI Terminal UI |
| 2 | + |
| 3 | +The terminal UI lets you search, install, update and remove software without opening the |
| 4 | +UniGetUI desktop window. It is included with UniGetUI; no separate terminal application or |
| 5 | +package is needed. |
| 6 | + |
| 7 | +It uses the same package managers, settings, installation options, ignored updates, bundles |
| 8 | +and operation history as the desktop app. **In normal mode, your actions affect the software |
| 9 | +on your computer.** Your saved automatic-update and scheduled-maintenance preferences also |
| 10 | +apply. Use [demo mode](#try-it-without-changing-your-computer) to explore safely. |
| 11 | + |
| 12 | +## Getting started |
| 13 | + |
| 14 | +Install UniGetUI using the [installation guide](../README.md#installation). You do not need |
| 15 | +to build it from source to use the terminal UI. |
| 16 | + |
| 17 | +If `uniget` is on your `PATH`, open a terminal and run: |
| 18 | + |
| 19 | +```shell |
| 20 | +uniget tui |
| 21 | +``` |
| 22 | + |
| 23 | +Otherwise, use the launcher included with your installation: |
| 24 | + |
| 25 | +| Platform | How to start | |
| 26 | +| --- | --- | |
| 27 | +| Windows | Open PowerShell in the UniGetUI installation folder and run `.\uniget.exe tui`. | |
| 28 | +| Linux | Installed `.deb` and `.rpm` packages provide `uniget tui`. From an extracted archive, open its folder and run `./uniget tui`. | |
| 29 | +| macOS | After installing in Applications, run `/Applications/UniGetUI.app/Contents/MacOS/uniget tui`. From an extracted archive, run `./uniget tui` in its folder. | |
| 30 | + |
| 31 | +On Windows, selecting **Add to PATH** during installation lets you use `uniget` from any |
| 32 | +folder. Open a new terminal after installation. Portable installations do not change `PATH`; |
| 33 | +run the launcher from the portable folder. See [the CLI guide](CLI.md#quick-start) for more |
| 34 | +launch options and [portable mode](PORTABLE.md) for portable installation details. |
| 35 | + |
| 36 | +**In PowerShell, use `uniget.exe`, not `UniGetUI.exe` directly.** The launcher keeps PowerShell |
| 37 | +waiting while you use the TUI. If you need to launch `UniGetUI.exe` itself, run this from its |
| 38 | +installation folder: |
| 39 | + |
| 40 | +```powershell |
| 41 | +Start-Process -FilePath .\UniGetUI.exe -ArgumentList 'tui' -NoNewWindow -Wait |
| 42 | +``` |
| 43 | + |
| 44 | +At startup, a version banner and `Initializing UniGetUI engine (loading package managers)...` |
| 45 | +appear while your package managers load. The interactive screen opens afterwards; there is |
| 46 | +no progress bar during this initial step. |
| 47 | + |
| 48 | +Press **F1** for help at any time and **Ctrl+Q** to quit. |
| 49 | + |
| 50 | +## Try it without changing your computer |
| 51 | + |
| 52 | +Demo mode provides sample packages so you can try searching, installing, updating and |
| 53 | +uninstalling without calling real package managers or changing your normal UniGetUI settings: |
| 54 | + |
| 55 | +```shell |
| 56 | +uniget tui --fake-data |
| 57 | +``` |
| 58 | + |
| 59 | +If `uniget` is not on your `PATH`, use the same platform-specific launcher as above, followed |
| 60 | +by `tui --fake-data`. |
| 61 | + |
| 62 | +The screen displays **FAKE DATA** throughout the session. Packages and operations are |
| 63 | +simulated, downloads do not use the network, and cloud backups stay in a local demo folder. |
| 64 | +Links and "open" actions show their target instead of launching another application. |
| 65 | +Actions that would change your real machine, such as repairing WinGet or managing desktop |
| 66 | +shortcuts, are unavailable. |
| 67 | + |
| 68 | +To keep your demo settings and sample package changes between sessions, choose a dedicated |
| 69 | +folder and reuse it: |
| 70 | + |
| 71 | +```shell |
| 72 | +uniget tui --fake-data-dir "my-tui-demo" |
| 73 | +``` |
| 74 | + |
| 75 | +Without a chosen folder, each launch uses a new temporary sandbox. |
| 76 | + |
| 77 | +## Find your way around |
| 78 | + |
| 79 | +The numbered tabs take you to each page. Use **Alt+1** through **Alt+9**, or click a tab. |
| 80 | +**Ctrl+Tab** and **Ctrl+Shift+Tab** move to the next and previous pages. Some terminals also |
| 81 | +support **Ctrl+1** through **Ctrl+9**. |
| 82 | + |
| 83 | +| Tab | What you can do | |
| 84 | +| --- | --- | |
| 85 | +| 1 Discover | Search for packages and install them. | |
| 86 | +| 2 Updates | Review available updates, update packages, or ignore and pause updates. | |
| 87 | +| 3 Installed | View installed packages, uninstall or reinstall them, and open installation locations. | |
| 88 | +| 4 Bundles | Create, open, save and install lists of packages. | |
| 89 | +| 5 Operations | Follow installation progress and output, cancel operations, or retry failures. | |
| 90 | +| 6 Managers | Check package manager status, enable or disable managers, and manage package sources. | |
| 91 | +| 7 Settings | Change preferences, default installation options, update behavior, backups and scheduled maintenance. | |
| 92 | +| 8 Logs | Read and export UniGetUI and package manager logs. | |
| 93 | +| 9 History | Review previous operations, view their logs, or run them again. | |
| 94 | + |
| 95 | +Use **Tab** and **Shift+Tab** to move between controls. **F10** opens the menu bar; use the |
| 96 | +arrow keys to choose a menu or action, then **Enter** to activate it. The **Page** menu |
| 97 | +contains actions for the page you are viewing. |
| 98 | + |
| 99 | +## Common tasks |
| 100 | + |
| 101 | +### Search for and install a package |
| 102 | + |
| 103 | +1. Open **Discover** with **Alt+1**, press **Ctrl+F**, type a package name or ID, and press **Enter**. |
| 104 | +2. When results appear, press **Down** to move to the list and use the arrow keys to highlight |
| 105 | + a package. Press **Enter** to view its details. |
| 106 | +3. Back in the list, press **Ctrl+Enter** to install the highlighted package, or **o** to review |
| 107 | + installation options first. Use **Space** to select multiple packages for a batch installation. |
| 108 | + |
| 109 | +The source, sort and search-mode controls above the list let you narrow the results. |
| 110 | +Press **m** in the list to see all available actions for the package. |
| 111 | + |
| 112 | +### Update or remove packages |
| 113 | + |
| 114 | +Open **Updates** with **Alt+2** or **Installed** with **Alt+3**. Review the packages and use |
| 115 | +**Space** to select or unselect them. **Ctrl+Enter** updates packages on the Updates page |
| 116 | +and uninstalls packages on the Installed page. It acts on checked packages, or on the |
| 117 | +highlighted package if none are checked. |
| 118 | + |
| 119 | +Updates are selected by default unless you have changed that preference. Check the selection |
| 120 | +before starting a batch. Press **m** for other actions, such as ignoring an update, skipping |
| 121 | +a version, pausing updates or reinstalling a package. |
| 122 | + |
| 123 | +### Choose installation options |
| 124 | + |
| 125 | +In a package list, press **o** to choose options such as version, architecture, installation |
| 126 | +scope or location, additional command-line arguments, and administrator or interactive mode. |
| 127 | +Available choices depend on the package manager. Some operations require administrator |
| 128 | +permission. |
| 129 | + |
| 130 | +### Follow an operation or investigate a failure |
| 131 | + |
| 132 | +Open **Operations** with **Alt+5** to see progress and command output. Use its actions to |
| 133 | +cancel or retry an operation. **History** keeps previous operations and their logs, while |
| 134 | +**Logs** provides application and package manager diagnostics. |
| 135 | + |
| 136 | +### Work with package bundles |
| 137 | + |
| 138 | +Use **Bundles** to create or open a list of packages, save it, and install its contents. |
| 139 | +Supported bundle formats are `.ubundle`, `.json`, `.yaml` and `.xml`. You can also open an |
| 140 | +existing bundle when starting the TUI: |
| 141 | + |
| 142 | +```shell |
| 143 | +uniget tui "my-packages.ubundle" |
| 144 | +``` |
| 145 | + |
| 146 | +Review any bundle security warnings before confirming installation. |
| 147 | + |
| 148 | +## Keyboard |
| 149 | + |
| 150 | +These shortcuts apply when the relevant page or package list has focus. When typing into |
| 151 | +a text field, ordinary letters enter text instead of running package actions. |
| 152 | + |
| 153 | +| Keys | Action | |
| 154 | +| --- | --- | |
| 155 | +| Alt+1 through Alt+9 | Go to a numbered page tab | |
| 156 | +| Ctrl+Tab / Ctrl+Shift+Tab | Next / previous page | |
| 157 | +| Tab / Shift+Tab | Next / previous control | |
| 158 | +| Esc | Close a dialog or menu, or return from a search field to the list | |
| 159 | +| F10 | Open the menu bar | |
| 160 | +| Alt+letter | Open a menu using its highlighted access letter | |
| 161 | +| F1 | Open help | |
| 162 | +| F5 or Ctrl+R | Reload the current page | |
| 163 | +| Ctrl+F or `/` | Focus search or filtering | |
| 164 | +| Ctrl+A | Select all packages | |
| 165 | +| Ctrl+Q | Quit | |
| 166 | +| Space | Select or unselect the highlighted package | |
| 167 | +| Enter | View package details | |
| 168 | +| Ctrl+Enter | Install, update or uninstall, depending on the page | |
| 169 | +| `o` or Alt+Enter | Open installation options | |
| 170 | +| `m` | Show all actions for the package | |
| 171 | +| `i` / `u` / `x` | Install / update / uninstall | |
| 172 | +| `b` | Add packages to a bundle | |
| 173 | +| `g` | Ignore updates | |
| 174 | +| `f` / `s` / F3 | Filter by source / sort / change search mode | |
| 175 | + |
| 176 | +Inside dialogs, use **Tab** to move between fields, the arrow keys to change choices, |
| 177 | +**Enter** to activate a control, and **Esc** to cancel. |
| 178 | + |
| 179 | +## Themes |
| 180 | + |
| 181 | +Choose a theme in **View > Theme** or **Settings > User interface preferences > Theme**. |
| 182 | +The change appears immediately and is saved for future sessions. |
| 183 | + |
| 184 | +The default is **Devolutions - Graphite**. Other choices include Devolutions Black, Light, |
| 185 | +Dark Blue, Blue, Gray and High contrast, plus Dracula, Monokai, Nord, Gruvbox Dark, |
| 186 | +Solarized Dark, Solarized Light, One Dark, Tokyo Night and Catppuccin Mocha. |
| 187 | + |
| 188 | +Use **High contrast** if you need stronger separation between text, controls and backgrounds. |
| 189 | +Older 16-colour consoles display approximate theme colours. |
| 190 | + |
| 191 | +For a temporary theme, use `--theme <id>`. Run `uniget tui --help` to see the theme IDs. |
| 192 | + |
| 193 | +## Startup options |
| 194 | + |
| 195 | +Add these options after `uniget tui`: |
| 196 | + |
| 197 | +| Option | What it does | |
| 198 | +| --- | --- | |
| 199 | +| `--page <id>` | Start on `discover`, `updates`, `installed`, `bundles`, `operations`, `managers`, `settings`, `logs` or `history`. `help` and `about` open their dialogs. | |
| 200 | +| `--theme <id>` | Choose a theme for this session without saving it. | |
| 201 | +| `--fake-data` | Explore with simulated packages and separate settings. | |
| 202 | +| `--fake-data-dir <folder>` | Explore with simulated packages and keep demo state in the chosen folder. | |
| 203 | +| `--updateapps` | Start updating every available package after the update check finishes. | |
| 204 | +| `<bundle-file>` | Open an existing `.ubundle`, `.json`, `.yaml` or `.xml` package bundle. | |
| 205 | +| `--help` | Show usage, settings commands and theme IDs, then exit. | |
| 206 | + |
| 207 | +For example, open the Updates page to review available updates: |
| 208 | + |
| 209 | +```shell |
| 210 | +uniget tui --page updates |
| 211 | +``` |
| 212 | + |
| 213 | +**Use `--updateapps` only when you intend to update all available packages.** Unlike |
| 214 | +`--page updates`, it requests automatic updates rather than just choosing the starting page. |
| 215 | +Your saved automatic-update preferences still apply without this option. |
| 216 | + |
| 217 | +Settings import, export and individual setting changes can also be run without opening the |
| 218 | +interactive screen. Use `uniget tui --help` for their syntax. |
| 219 | + |
| 220 | +## Differences from the desktop app |
| 221 | + |
| 222 | +Most package-management tasks are available in both interfaces. The terminal UI displays |
| 223 | +progress and notifications within the terminal rather than using a tray icon or system |
| 224 | +notifications. Settings that only affect the desktop window are labelled **(desktop app)**. |
| 225 | + |
| 226 | +The TUI does not update UniGetUI itself. Install application updates through the desktop app |
| 227 | +or your usual installation method; the **Help** menu links to the release page. |
| 228 | +The Devolutions Agent policy inspector and editor are available only in the desktop app. |
| 229 | + |
| 230 | +## Troubleshooting |
| 231 | + |
| 232 | +| Problem | What to try | |
| 233 | +| --- | --- | |
| 234 | +| `uniget` is not recognized | Open a new terminal after adding UniGetUI to `PATH`, or run the launcher from the installation folder. | |
| 235 | +| PowerShell shows another prompt while the TUI starts, or reports "The parameter is incorrect" | Use `.\uniget.exe tui`, or the explicit `Start-Process` command above. Do not launch `.\UniGetUI.exe tui` directly from an interactive PowerShell prompt. | |
| 236 | +| The startup screen stays on "loading package managers" | Initialization must finish before the interactive screen appears. If startup fails, keep the error message for troubleshooting. | |
| 237 | +| A package manager is unavailable or a package action is missing | Check **Managers** for its status and enabled state. Available actions depend on the manager and platform. | |
| 238 | +| Alt shortcuts do not work | Use **F10** and the arrow keys for menus. On macOS Terminal, enable **Settings > Profiles > Keyboard > Use Option as Meta key**. | |
| 239 | +| Alt+Enter switches Windows Terminal to full screen | Use **o** to open installation options instead. | |
| 240 | +| Colours look different or menu letters are not underlined | Try a modern terminal such as Windows Terminal. Older consoles have a smaller colour palette. | |
| 241 | + |
| 242 | +Run the TUI in an interactive terminal, not with its input or output redirected to a file or |
| 243 | +pipeline. |
| 244 | + |
| 245 | +For more help, press **F1** or use the **Help** menu. When reporting a problem, include your |
| 246 | +UniGetUI version, operating system, terminal application, and the error or relevant logs. |
| 247 | +**Help > About** provides terminal diagnostics, and **Logs** lets you export logs for review. |
0 commit comments