chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
+262
@@ -0,0 +1,262 @@
|
||||
# UniGetUI command-line interface
|
||||
|
||||
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 developer-only Avalonia diagnostics toggles, see the project source and build props; they are intentionally not documented here as public CLI arguments.
|
||||
|
||||
## Quick start
|
||||
|
||||
```powershell
|
||||
unigetui status
|
||||
unigetui app status
|
||||
unigetui package search --manager dotnet-tool --query dotnetsay
|
||||
unigetui package install --manager dotnet-tool --id dotnetsay --version 2.1.4 --scope Global
|
||||
unigetui operation wait --id 123 --timeout 300
|
||||
```
|
||||
|
||||
## Global transport options
|
||||
|
||||
These options select how the CLI connects to the local UniGetUI automation session.
|
||||
|
||||
| Option | Meaning |
|
||||
| --- | --- |
|
||||
| `--transport {named-pipe\|tcp}` | Client-side transport override. Default is `named-pipe`. |
|
||||
| `--tcp-port <port>` | Client-side TCP port override. Used only with `tcp`. |
|
||||
| `--pipe-name <name-or-path>` | Client-side named-pipe override. On Windows this is a pipe name. On non-Windows a relative name resolves under `/tmp`, while an absolute path uses that exact Unix socket path. |
|
||||
|
||||
Related environment variables:
|
||||
|
||||
| Variable | Meaning |
|
||||
| --- | --- |
|
||||
| `UNIGETUI_IPC_API_TRANSPORT` | Same as `--transport`. |
|
||||
| `UNIGETUI_IPC_API_PORT` | Same as `--tcp-port`. |
|
||||
| `UNIGETUI_IPC_API_PIPE_NAME` | Same as `--pipe-name`. |
|
||||
|
||||
## Exit codes
|
||||
|
||||
| Code | Meaning |
|
||||
| --- | --- |
|
||||
| `0` | Success |
|
||||
| `1` | Command failed |
|
||||
| `2` | Invalid parameter |
|
||||
| `3` | IPC API unavailable |
|
||||
| `4` | Unknown automation command |
|
||||
|
||||
## Command grammar notes
|
||||
|
||||
- Command nouns accept singular or plural forms: `operation`/`operations`, `package`/`packages`, `manager`/`managers`, and so on.
|
||||
- Compatibility aliases are accepted for some flags:
|
||||
- `--id` maps to `--package-id` or `--operation-id` where appropriate
|
||||
- `--source` maps to `--package-source`
|
||||
- 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`.
|
||||
|
||||
## Command reference
|
||||
|
||||
### Core
|
||||
|
||||
| Command | Required options | Optional options | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `status` | None | None | Returns transport, endpoint, and build information for the selected automation session. |
|
||||
| `version` | None | None | Returns the UniGetUI build number through the IPC API. |
|
||||
|
||||
### App
|
||||
|
||||
| Command | Required options | Optional options | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `app status` | None | None | Returns app/session state such as headless mode, page, and supported UI actions. |
|
||||
| `app show` | None | None | Shows and focuses the window when a GUI session exists. |
|
||||
| `app navigate` | `--page <page>` | `--manager <id>`, `--help-attachment <path>` | Valid pages include `discover`, `updates`, `installed`, `bundles`, `settings`, `managers`, `own-log`, `manager-log`, `operation-history`, `help`, `release-notes`, and `about`. |
|
||||
| `app quit` | None | None | Gracefully shuts down the selected session, including headless daemons. |
|
||||
|
||||
### Operations
|
||||
|
||||
| Command | Required options | Optional options | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `operation list` | None | None | Lists tracked live and completed operations. |
|
||||
| `operation get` | `--id <operation-id>` | None | Returns the full tracked payload for one operation. |
|
||||
| `operation output` | `--id <operation-id>` | `--tail <n>` | Reads captured output lines for one operation. |
|
||||
| `operation wait` | `--id <operation-id>` | `--timeout <seconds>`, `--delay <seconds>` | Polls until the operation reaches a terminal state. |
|
||||
| `operation cancel` | `--id <operation-id>` | None | Cancels a queued or running operation. |
|
||||
| `operation retry` | `--id <operation-id>` | `--mode <mode>` | Retry modes are defined by the operation payload. |
|
||||
| `operation reorder` | `--id <operation-id>`, `--action <run-now\|run-next\|run-last>` | None | Reorders a queued operation. |
|
||||
| `operation forget` | `--id <operation-id>` | None | Removes a finished operation from the live tracked list. |
|
||||
|
||||
### Managers
|
||||
|
||||
| Command | Required options | Optional options | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `manager list` | None | None | Lists managers and their automation-relevant capability flags. |
|
||||
| `manager maintenance` | `--manager <id>` | None | Returns maintenance metadata for one manager. |
|
||||
| `manager reload` | `--manager <id>` | None | Reloads one manager. |
|
||||
| `manager set-executable` | `--manager <id>`, `--path <path>` | None | Sets a custom executable override, then reloads the manager. |
|
||||
| `manager clear-executable` | `--manager <id>` | None | Clears the custom executable override, then reloads the manager. |
|
||||
| `manager action` | `--manager <id>`, `--action <action>` | `--confirm` | Runs a manager-specific maintenance action. |
|
||||
| `manager enable` | `--manager <id>` | None | Enables the manager. |
|
||||
| `manager disable` | `--manager <id>` | None | Disables the manager. |
|
||||
| `manager notifications enable` | `--manager <id>` | None | Enables update notifications for the manager. |
|
||||
| `manager notifications disable` | `--manager <id>` | None | Disables update notifications for the manager. |
|
||||
|
||||
### Sources
|
||||
|
||||
| Command | Required options | Optional options | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `source list` | None | `--manager <id>` | Lists sources, optionally filtered to one manager. |
|
||||
| `source add` | `--manager <id>`, `--name <source-name>` | `--url <source-url>` | Adds a source. |
|
||||
| `source remove` | `--manager <id>`, `--name <source-name>` | `--url <source-url>` | Removes a source. |
|
||||
|
||||
### Settings
|
||||
|
||||
| Command | Required options | Optional options | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `settings list` | None | None | Lists non-secure settings. |
|
||||
| `settings get` | `--key <key>` | None | Reads one non-secure setting. |
|
||||
| `settings set` | `--key <key>` | `--enabled true\|false`, `--value <text>` | Sets either the boolean or string form of a setting. |
|
||||
| `settings clear` | `--key <key>` | None | Clears a string-backed setting. |
|
||||
| `settings reset` | None | None | Resets non-secure settings. |
|
||||
| `settings secure list` | None | `--user <name>` | Lists secure settings for the current or specified user. |
|
||||
| `settings secure get` | `--key <key>` | `--user <name>` | Reads one secure setting. |
|
||||
| `settings secure set` | `--key <key>`, `--enabled true\|false` | `--user <name>` | Enables or disables one secure setting. |
|
||||
|
||||
Available keys live in:
|
||||
|
||||
- [`src/UniGetUI.Core.Settings/SettingsEngine_Names.cs`](src/UniGetUI.Core.Settings/SettingsEngine_Names.cs)
|
||||
- [`src/UniGetUI.Core.SecureSettings/SecureSettings.cs`](src/UniGetUI.Core.SecureSettings/SecureSettings.cs)
|
||||
|
||||
### Shortcuts
|
||||
|
||||
| Command | Required options | Optional options | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `shortcut list` | None | None | Lists tracked desktop shortcuts and stored keep/delete verdicts. |
|
||||
| `shortcut set` | `--path <path>`, `--status <keep\|delete>` | None | Marks a shortcut to keep or delete. |
|
||||
| `shortcut reset` | `--path <path>` | None | Clears the stored verdict for one shortcut. |
|
||||
| `shortcut reset-all` | None | None | Clears all stored shortcut verdicts. |
|
||||
|
||||
### Logs
|
||||
|
||||
| Command | Required options | Optional options | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `log app` | None | `--level <n>` | Returns structured application log entries. |
|
||||
| `log operations` | None | None | Returns persisted operation history. |
|
||||
| `log manager` | None | `--manager <id>`, `--verbose` | Returns manager task logs. |
|
||||
|
||||
### Backups
|
||||
|
||||
| Command | Required options | Optional options | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `backup status` | None | None | Returns backup settings and cloud-auth state. |
|
||||
| `backup local create` | None | None | Creates a local backup bundle. |
|
||||
| `backup github login start` | None | `--launch-browser` | Starts the GitHub device flow. |
|
||||
| `backup github login complete` | None | None | Completes the pending device flow. |
|
||||
| `backup github logout` | None | None | Clears the stored GitHub auth token. |
|
||||
| `backup cloud list` | None | None | Lists cloud backups in the authenticated GitHub backup store. |
|
||||
| `backup cloud create` | None | None | Uploads the current backup to cloud storage. |
|
||||
| `backup cloud download` | `--key <name>` | None | Downloads one cloud backup as bundle content. |
|
||||
| `backup cloud restore` | `--key <name>` | `--append` | Imports one cloud backup into the current in-memory bundle. |
|
||||
|
||||
### Bundles
|
||||
|
||||
| Command | Required options | Optional options | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `bundle get` | None | None | Returns the current in-memory bundle. |
|
||||
| `bundle reset` | None | None | Clears the current in-memory bundle. |
|
||||
| `bundle import` | None | `--path <path>`, `--content <text>`, `--format <ubundle\|json\|yaml\|xml>`, `--append` | Imports bundle content from a file or raw content. |
|
||||
| `bundle export` | None | `--path <path>` | Exports the current bundle, optionally to disk. |
|
||||
| `bundle add` | `--id <package-id>` | `--manager <id>`, `--source <source>`, `--version <version>`, `--scope <scope>`, `--pre-release`, `--selection <search\|installed\|updates\|auto>` | Resolves a package and adds it to the bundle. |
|
||||
| `bundle remove` | `--id <package-id>` | `--manager <id>`, `--source <source>`, `--version <version>`, `--scope <scope>`, `--pre-release`, `--selection <mode>` | Removes matching package entries from the bundle. |
|
||||
| `bundle install` | None | `--include-installed true\|false`, `--elevated true\|false`, `--interactive true\|false`, `--skip-hash true\|false` | Installs the bundle through UniGetUI’s shared operation pipeline. |
|
||||
|
||||
### Packages
|
||||
|
||||
| Command | Required options | Optional options | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `package search` | `--query <text>` | `--manager <id>`, `--max-results <n>` | Searches packages. |
|
||||
| `package details` | `--id <package-id>` | `--manager <id>`, `--source <source>` | Returns the package details payload. |
|
||||
| `package versions` | `--id <package-id>` | `--manager <id>`, `--source <source>` | Returns installable versions when supported by the manager. |
|
||||
| `package installed` | None | `--manager <id>` | Lists installed packages. |
|
||||
| `package updates` | None | `--manager <id>` | Lists available updates. |
|
||||
| `package install` | `--id <package-id>` | `--manager <id>`, `--source <source>`, `--version <version>`, `--scope <scope>`, `--pre-release`, `--elevated true\|false`, `--interactive true\|false`, `--skip-hash true\|false`, `--architecture <value>`, `--location <path>`, `--wait true\|false`, `--detach` | Installs a package. Async mode returns an operation id immediately. |
|
||||
| `package download` | `--id <package-id>` | `--manager <id>`, `--source <source>`, `--version <version>`, `--scope <scope>`, `--wait true\|false`, `--detach`, `--output <path>` | Downloads a package artifact. |
|
||||
| `package reinstall` | `--id <package-id>` | Same options as `package install` | Re-runs installation for an installed package. |
|
||||
| `package repair` | `--id <package-id>` | Same options as `package install`, plus `--remove-data true\|false` | Uninstalls then reinstalls the package. |
|
||||
| `package update` | `--id <package-id>` | Same options as `package install` | Updates one package. |
|
||||
| `package uninstall` | `--id <package-id>` | `--manager <id>`, `--source <source>`, `--scope <scope>`, `--remove-data true\|false`, `--elevated true\|false`, `--interactive true\|false`, `--wait true\|false`, `--detach` | Uninstalls a package. |
|
||||
| `package show` | `--id <package-id>`, `--source <source>` | None | Opens the package details UI flow. |
|
||||
| `package ignored list` | None | None | Lists ignored-update rules tracked by UniGetUI. |
|
||||
| `package ignored add` | `--id <package-id>` | `--manager <id>`, `--version <version>`, `--source <source>` | Adds an ignored-update rule. |
|
||||
| `package ignored remove` | `--id <package-id>` | `--manager <id>`, `--version <version>`, `--source <source>` | Removes an ignored-update rule. |
|
||||
| `package update-all` | None | None | Queues updates for all currently upgradable packages. |
|
||||
| `package update-manager` | `--manager <id>` | None | Queues updates for all upgradable packages handled by one manager. |
|
||||
|
||||
## Headless behavior
|
||||
|
||||
When UniGetUI is started with `--headless`, it exposes the same automation API without opening a window.
|
||||
|
||||
| Command | Headless behavior |
|
||||
| --- | --- |
|
||||
| `status`, `app status`, `app quit` | Fully supported. |
|
||||
| `app show` | Fails with “the current UniGetUI session is running headless and has no window to show.” |
|
||||
| `app navigate` | Fails with “the current UniGetUI session is running headless and cannot navigate UI pages.” |
|
||||
| `package show` | UI-oriented; may fail or be meaningless in pure headless sessions. |
|
||||
| `package update-all`, `package update-manager` | Require GUI-side upgrade handlers. Headless sessions may return “cannot update all packages” or “cannot update manager packages.” |
|
||||
|
||||
## Headless IPC options
|
||||
|
||||
When UniGetUI is started with `--headless`, these options control the IPC listener:
|
||||
|
||||
| Option | Meaning |
|
||||
| --- | --- |
|
||||
| `--ipc-api-transport {named-pipe\|tcp}` | Selects the server-side IPC transport. Default is `named-pipe`. |
|
||||
| `--ipc-api-port <port>` | Overrides the TCP port when TCP transport is selected. |
|
||||
| `--ipc-api-pipe-name <name-or-path>` | Overrides the server-side pipe name or Unix socket path. |
|
||||
|
||||
## Other application startup parameters
|
||||
|
||||
These parameters are accepted by the app executables in addition to the automation verb tree.
|
||||
|
||||
| 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. |
|
||||
| `--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 <file>` | Imports settings from a JSON file. | Existing settings are replaced. |
|
||||
| `--export-settings <file>` | Exports settings to a JSON file. | Creates or overwrites the file. |
|
||||
| `--enable-setting <key>` / `--disable-setting <key>` | Toggles one boolean setting. | Legacy setting flags. |
|
||||
| `--set-setting-value <key> <value>` | Sets one string-backed setting. | Legacy setting flag. |
|
||||
| `--no-corrupt-dialog` | Shows the verbose crash report instead of the simplified dialog. | Troubleshooting flag. |
|
||||
| `--enable-secure-setting <key>` / `--disable-secure-setting <key>` | Toggles one secure setting for the current user. | May require elevation. |
|
||||
| `--enable-secure-setting-for-user <user> <key>` / `--disable-secure-setting-for-user <user> <key>` | Toggles one secure setting for a specified user. | May require elevation. |
|
||||
| `<bundle-file>` | Loads a valid bundle file into the Package Bundles page. | Supported extensions include `.ubundle`, `.json`, `.yaml`, and `.xml`. |
|
||||
|
||||
## Deep links
|
||||
|
||||
UniGetUI also accepts the following `unigetui://` links:
|
||||
|
||||
| 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. |
|
||||
|
||||
## Installer parameters
|
||||
|
||||
The installer is Inno Setup based. It supports the standard [Inno Setup command-line parameters](https://jrsoftware.org/ishelp/index.php?topic=setupcmdline) plus these UniGetUI-specific switches:
|
||||
|
||||
| Parameter | Meaning |
|
||||
| --- | --- |
|
||||
| `/NoAutoStart` | Do not launch UniGetUI after installation. |
|
||||
| `/NoRunOnStartup` | Do not register UniGetUI to start minimized at login. |
|
||||
| `/NoVCRedist` | Skip installation of the MSVC x64 runtime. |
|
||||
| `/NoEdgeWebView` | Skip installation of the Microsoft Edge WebView runtime. |
|
||||
| `/NoChocolatey` | Deprecated no-op kept for compatibility. |
|
||||
| `/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. |
|
||||
+397
@@ -0,0 +1,397 @@
|
||||
# UniGetUI background IPC API
|
||||
|
||||
This file documents the **local automation API** used by the UniGetUI CLI.
|
||||
|
||||
- For the public command-line interface built on top of this API, see [CLI.md](CLI.md).
|
||||
- This API is designed for **local automation**, not for remote exposure.
|
||||
|
||||
## Overview
|
||||
|
||||
UniGetUI exposes a local HTTP API over one of two transports:
|
||||
|
||||
- **Named-pipe transport** (default)
|
||||
- Windows: Windows named pipe
|
||||
- Non-Windows: Unix domain socket
|
||||
- **TCP transport** (optional)
|
||||
- Localhost only
|
||||
|
||||
All endpoints live under `/uniget/v1/...`.
|
||||
|
||||
## Transport defaults
|
||||
|
||||
| Setting | Value |
|
||||
| --- | --- |
|
||||
| Default transport | `named-pipe` |
|
||||
| Default TCP port | `7058` |
|
||||
| Default pipe name | `UniGetUI.IPC` |
|
||||
| Default Unix socket directory | `/tmp` |
|
||||
|
||||
On non-Windows, a relative named-pipe name such as `UniGetUI.IPC` resolves to:
|
||||
|
||||
```text
|
||||
/tmp/UniGetUI.IPC
|
||||
```
|
||||
|
||||
An absolute path may also be supplied on non-Windows. On Windows, absolute pipe paths are rejected and UniGetUI falls back to the default pipe name.
|
||||
|
||||
## Server-side configuration
|
||||
|
||||
These options are read when UniGetUI starts its IPC API server.
|
||||
|
||||
| Argument | Environment variable | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `--ipc-api-transport {named-pipe\|tcp}` | `UNIGETUI_IPC_API_TRANSPORT` | Selects the server transport. |
|
||||
| `--ipc-api-port <port>` | `UNIGETUI_IPC_API_PORT` | Selects the TCP port when TCP is enabled. |
|
||||
| `--ipc-api-pipe-name <name-or-path>` | `UNIGETUI_IPC_API_PIPE_NAME` | Selects the pipe name or Unix socket path when named-pipe transport is enabled. |
|
||||
|
||||
## Client-side configuration
|
||||
|
||||
These options are read by the CLI and `IpcClient`.
|
||||
|
||||
| Argument | Environment variable | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `--transport {named-pipe\|tcp}` | `UNIGETUI_IPC_API_TRANSPORT` | Explicit client-side transport override. |
|
||||
| `--tcp-port <port>` | `UNIGETUI_IPC_API_PORT` | Explicit client-side TCP port override. |
|
||||
| `--pipe-name <name-or-path>` | `UNIGETUI_IPC_API_PIPE_NAME` | Explicit client-side pipe name or Unix socket override. |
|
||||
|
||||
## Session discovery
|
||||
|
||||
When the client does **not** receive an explicit transport override:
|
||||
|
||||
1. UniGetUI loads persisted endpoint registrations from the user configuration directory.
|
||||
2. Registrations are ordered with this preference:
|
||||
1. headless sessions first
|
||||
2. newest persisted session first
|
||||
3. The client probes for a live session and uses its persisted token automatically.
|
||||
|
||||
When the client **does** receive an explicit override:
|
||||
|
||||
- it connects to that transport choice instead of auto-selecting the newest session
|
||||
- it waits up to 5 seconds for a matching persisted token to appear
|
||||
|
||||
## Authentication
|
||||
|
||||
| Endpoint | Auth |
|
||||
| --- | --- |
|
||||
| `GET /uniget/v1/status` | No token required |
|
||||
| All other `/uniget/v1/*` endpoints | `token` query parameter required |
|
||||
|
||||
Authentication details:
|
||||
|
||||
- UniGetUI generates a per-session token at API startup.
|
||||
- That token is persisted with the endpoint registration metadata.
|
||||
- `IpcClient` automatically appends `token=<value>` to authenticated requests.
|
||||
|
||||
## Security notes
|
||||
|
||||
- The default design is **local-only automation**.
|
||||
- TCP mode binds to `localhost`, not all interfaces.
|
||||
- On non-Windows named-pipe transport, UniGetUI applies Unix socket mode:
|
||||
|
||||
```text
|
||||
user-read + user-write
|
||||
```
|
||||
|
||||
That is effectively `0600`-style same-user access on the socket file.
|
||||
|
||||
- On Windows named-pipe transport, UniGetUI uses Kestrel named-pipe hosting and does not expose a filesystem socket path.
|
||||
|
||||
## Error model
|
||||
|
||||
| Condition | Result |
|
||||
| --- | --- |
|
||||
| Missing or invalid token | HTTP `401` |
|
||||
| Invalid query/body arguments | HTTP `400` with plain-text error message |
|
||||
| Success | JSON response with camelCase property names |
|
||||
|
||||
Most successful command endpoints return either:
|
||||
|
||||
- a domain object wrapped in a `status: "success"` envelope, or
|
||||
- a command/result JSON envelope, or
|
||||
- another typed JSON payload documented by its fields rather than its CLR type name
|
||||
|
||||
## Request conventions
|
||||
|
||||
### Query-string endpoints
|
||||
|
||||
Most endpoints use query parameters, including:
|
||||
|
||||
- operations
|
||||
- app navigation
|
||||
- sources
|
||||
- settings
|
||||
- secure settings
|
||||
- shortcuts
|
||||
- logs
|
||||
- package search/details/versions/installed/updates
|
||||
- package actions
|
||||
|
||||
### JSON-body endpoints
|
||||
|
||||
These endpoint families consume JSON bodies:
|
||||
|
||||
| Endpoint family | Request shape |
|
||||
| --- | --- |
|
||||
| manager maintenance actions | manager maintenance request body |
|
||||
| GitHub device-flow start | GitHub device-flow start request body |
|
||||
| cloud backup download/restore | cloud backup request body |
|
||||
| bundle import | bundle import request body |
|
||||
| bundle export | bundle export request body |
|
||||
| bundle add/remove | bundle package request body |
|
||||
| bundle install | bundle install request body |
|
||||
|
||||
### JSON body field reference
|
||||
|
||||
All request bodies use **camelCase** JSON.
|
||||
|
||||
#### Manager maintenance request body
|
||||
|
||||
| Field | Type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `managerName` | string | Required stable manager id |
|
||||
| `action` | string | Manager action name for `/action` |
|
||||
| `path` | string | Custom executable path for `/executable/set` |
|
||||
| `confirm` | boolean | Confirmation flag for destructive actions |
|
||||
|
||||
#### GitHub device-flow start request body
|
||||
|
||||
| Field | Type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `launchBrowser` | boolean | Whether UniGetUI should try to open the verification URL automatically |
|
||||
|
||||
#### Cloud backup request body
|
||||
|
||||
| Field | Type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `key` | string | Backup identifier |
|
||||
| `append` | boolean | Append instead of replace when restoring/importing |
|
||||
|
||||
#### Bundle import request body
|
||||
|
||||
| Field | Type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `path` | string | Source file path |
|
||||
| `content` | string | Raw bundle content |
|
||||
| `format` | string | Bundle format such as `ubundle`, `json`, `yaml`, or `xml` |
|
||||
| `append` | boolean | Append imported items to the current bundle |
|
||||
|
||||
#### Bundle export request body
|
||||
|
||||
| Field | Type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `path` | string | Optional output path |
|
||||
|
||||
#### Bundle package request body
|
||||
|
||||
| Field | Type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `packageId` | string | Package identifier |
|
||||
| `managerName` | string | Stable manager id |
|
||||
| `packageSource` | string | Source/feed name |
|
||||
| `version` | string | Requested version |
|
||||
| `scope` | string | Requested scope |
|
||||
| `preRelease` | boolean | Include prerelease package metadata |
|
||||
| `selection` | string | Bundle selection mode |
|
||||
|
||||
#### Bundle install request body
|
||||
|
||||
| Field | Type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `includeInstalled` | boolean | Whether already-installed packages should still be processed |
|
||||
| `elevated` | boolean | Request elevated execution |
|
||||
| `interactive` | boolean | Request interactive execution |
|
||||
| `skipHash` | boolean | Skip hash validation when supported |
|
||||
|
||||
## Shared parameter sets
|
||||
|
||||
### Package action query parameters
|
||||
|
||||
These keys are used by package-related endpoints such as install, update, uninstall, details, versions, ignored updates, and download.
|
||||
|
||||
| Query key | Meaning |
|
||||
| --- | --- |
|
||||
| `packageId` | Package identifier |
|
||||
| `manager` | Stable manager id |
|
||||
| `packageSource` | Source/feed name |
|
||||
| `version` | Requested version |
|
||||
| `scope` | Install scope |
|
||||
| `preRelease` | Boolean |
|
||||
| `elevated` | Boolean |
|
||||
| `interactive` | Boolean |
|
||||
| `skipHash` | Boolean |
|
||||
| `removeData` | Boolean |
|
||||
| `wait` | Boolean |
|
||||
| `architecture` | Architecture override |
|
||||
| `location` | Install location override |
|
||||
| `outputPath` | Download output path |
|
||||
|
||||
### App navigation query parameters
|
||||
|
||||
| Query key | Meaning |
|
||||
| --- | --- |
|
||||
| `page` | Target page name |
|
||||
| `manager` | Optional manager context |
|
||||
| `helpAttachment` | Optional help-page attachment |
|
||||
|
||||
### Operation query parameters
|
||||
|
||||
| Query key | Meaning |
|
||||
| --- | --- |
|
||||
| `tailLines` | Used by `GET /uniget/v1/operations/{operationId}/output` |
|
||||
| `mode` | Retry mode for `POST /uniget/v1/operations/{operationId}/retry` |
|
||||
| `action` | Queue action for `POST /uniget/v1/operations/{operationId}/reorder` |
|
||||
|
||||
## Endpoint reference
|
||||
|
||||
### Session and app
|
||||
|
||||
| Method | Path | Auth | Parameters/body | CLI equivalent | Notes |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `GET` | `/uniget/v1/status` | No | None | `status`, `version` | Returns `running`, `transport`, `tcpPort`, `namedPipeName`, `namedPipePath`, `baseAddress`, `version`, and `buildNumber`. |
|
||||
| `GET` | `/uniget/v1/app` | Yes | None | `app status` | Returns app/headless/window state. |
|
||||
| `POST` | `/uniget/v1/app/show` | Yes | None | `app show` | UI-only in practice. |
|
||||
| `POST` | `/uniget/v1/app/navigate` | Yes | Query: `page`, optional `manager`, optional `helpAttachment` | `app navigate` | UI-only in practice. |
|
||||
| `POST` | `/uniget/v1/app/quit` | Yes | None | `app quit` | Shuts down the selected session. |
|
||||
|
||||
### Operations
|
||||
|
||||
| Method | Path | Auth | Parameters/body | CLI equivalent |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `GET` | `/uniget/v1/operations` | Yes | None | `operation list` |
|
||||
| `GET` | `/uniget/v1/operations/{operationId}` | Yes | Route: `operationId` | `operation get` |
|
||||
| `GET` | `/uniget/v1/operations/{operationId}/output` | Yes | Route: `operationId`, optional query `tailLines` | `operation output` |
|
||||
| `POST` | `/uniget/v1/operations/{operationId}/cancel` | Yes | Route: `operationId` | `operation cancel` |
|
||||
| `POST` | `/uniget/v1/operations/{operationId}/retry` | Yes | Route: `operationId`, optional query `mode` | `operation retry` |
|
||||
| `POST` | `/uniget/v1/operations/{operationId}/reorder` | Yes | Route: `operationId`, query `action` | `operation reorder` |
|
||||
| `POST` | `/uniget/v1/operations/{operationId}/forget` | Yes | Route: `operationId` | `operation forget` |
|
||||
|
||||
### Managers
|
||||
|
||||
| Method | Path | Auth | Parameters/body | CLI equivalent |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `GET` | `/uniget/v1/managers` | Yes | None | `manager list` |
|
||||
| `GET` | `/uniget/v1/managers/maintenance` | Yes | Query `manager` | `manager maintenance` |
|
||||
| `POST` | `/uniget/v1/managers/maintenance/reload` | Yes | JSON body: manager maintenance request body | `manager reload` |
|
||||
| `POST` | `/uniget/v1/managers/maintenance/executable/set` | Yes | JSON body: manager maintenance request body | `manager set-executable` |
|
||||
| `POST` | `/uniget/v1/managers/maintenance/executable/clear` | Yes | JSON body: manager maintenance request body | `manager clear-executable` |
|
||||
| `POST` | `/uniget/v1/managers/maintenance/action` | Yes | JSON body: manager maintenance request body | `manager action` |
|
||||
| `POST` | `/uniget/v1/managers/set-enabled` | Yes | Query `manager`, `enabled` | `manager enable`, `manager disable` |
|
||||
| `POST` | `/uniget/v1/managers/set-update-notifications` | Yes | Query `manager`, `enabled` | `manager notifications enable`, `manager notifications disable` |
|
||||
|
||||
### Sources
|
||||
|
||||
| Method | Path | Auth | Parameters/body | CLI equivalent |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `GET` | `/uniget/v1/sources` | Yes | Optional query `manager` | `source list` |
|
||||
| `POST` | `/uniget/v1/sources/add` | Yes | Query `manager`, `name`, optional `url` | `source add` |
|
||||
| `POST` | `/uniget/v1/sources/remove` | Yes | Query `manager`, `name`, optional `url` | `source remove` |
|
||||
|
||||
### Settings
|
||||
|
||||
| Method | Path | Auth | Parameters/body | CLI equivalent |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `GET` | `/uniget/v1/settings` | Yes | None | `settings list` |
|
||||
| `GET` | `/uniget/v1/settings/item` | Yes | Query `key` | `settings get` |
|
||||
| `POST` | `/uniget/v1/settings/set` | Yes | Query `key`, optional `enabled`, optional `value` | `settings set` |
|
||||
| `POST` | `/uniget/v1/settings/clear` | Yes | Query `key` | `settings clear` |
|
||||
| `POST` | `/uniget/v1/settings/reset` | Yes | None | `settings reset` |
|
||||
|
||||
### Secure settings
|
||||
|
||||
| Method | Path | Auth | Parameters/body | CLI equivalent |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `GET` | `/uniget/v1/secure-settings` | Yes | Optional query `user` | `settings secure list` |
|
||||
| `GET` | `/uniget/v1/secure-settings/item` | Yes | Query `key`, optional `user` | `settings secure get` |
|
||||
| `POST` | `/uniget/v1/secure-settings/set` | Yes | Query `key`, `enabled`, optional `user` | `settings secure set` |
|
||||
|
||||
### Desktop shortcuts
|
||||
|
||||
| Method | Path | Auth | Parameters/body | CLI equivalent |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `GET` | `/uniget/v1/desktop-shortcuts` | Yes | None | `shortcut list` |
|
||||
| `POST` | `/uniget/v1/desktop-shortcuts/set` | Yes | Query `path`, `status` | `shortcut set` |
|
||||
| `POST` | `/uniget/v1/desktop-shortcuts/reset` | Yes | Query `path` | `shortcut reset` |
|
||||
| `POST` | `/uniget/v1/desktop-shortcuts/reset-all` | Yes | None | `shortcut reset-all` |
|
||||
|
||||
### Logs
|
||||
|
||||
| Method | Path | Auth | Parameters/body | CLI equivalent |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `GET` | `/uniget/v1/logs/app` | Yes | Optional query `level` | `log app` |
|
||||
| `GET` | `/uniget/v1/logs/history` | Yes | None | `log operations` |
|
||||
| `GET` | `/uniget/v1/logs/manager` | Yes | Optional query `manager`, optional query `verbose` | `log manager` |
|
||||
|
||||
### Backups
|
||||
|
||||
| Method | Path | Auth | Parameters/body | CLI equivalent | Notes |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `GET` | `/uniget/v1/backups/status` | Yes | None | `backup status` | Includes local backup settings and GitHub auth state. |
|
||||
| `POST` | `/uniget/v1/backups/local/create` | Yes | None | `backup local create` | Creates a local backup bundle. |
|
||||
| `POST` | `/uniget/v1/backups/github/sign-in/start` | Yes | JSON body: GitHub device-flow start request body | `backup github login start` | Starts GitHub device flow. |
|
||||
| `POST` | `/uniget/v1/backups/github/sign-in/complete` | Yes | None | `backup github login complete` | Completes device flow. |
|
||||
| `POST` | `/uniget/v1/backups/github/sign-out` | Yes | None | `backup github logout` | Signs out of GitHub backup integration. |
|
||||
| `GET` | `/uniget/v1/backups/cloud` | Yes | None | `backup cloud list` | Lists cloud backups. |
|
||||
| `POST` | `/uniget/v1/backups/cloud/create` | Yes | None | `backup cloud create` | Uploads a cloud backup. |
|
||||
| `POST` | `/uniget/v1/backups/cloud/download` | Yes | JSON body: cloud backup request body | `backup cloud download` | Downloads backup content. |
|
||||
| `POST` | `/uniget/v1/backups/cloud/restore` | Yes | JSON body: cloud backup request body | `backup cloud restore` | Restores/imports a cloud backup. |
|
||||
|
||||
### Bundles
|
||||
|
||||
| Method | Path | Auth | Parameters/body | CLI equivalent |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `GET` | `/uniget/v1/bundles` | Yes | None | `bundle get` |
|
||||
| `POST` | `/uniget/v1/bundles/reset` | Yes | None | `bundle reset` |
|
||||
| `POST` | `/uniget/v1/bundles/import` | Yes | JSON body: bundle import request body | `bundle import` |
|
||||
| `POST` | `/uniget/v1/bundles/export` | Yes | JSON body: bundle export request body | `bundle export` |
|
||||
| `POST` | `/uniget/v1/bundles/add` | Yes | JSON body: bundle package request body | `bundle add` |
|
||||
| `POST` | `/uniget/v1/bundles/remove` | Yes | JSON body: bundle package request body | `bundle remove` |
|
||||
| `POST` | `/uniget/v1/bundles/install` | Yes | JSON body: bundle install request body | `bundle install` |
|
||||
|
||||
### Packages
|
||||
|
||||
| Method | Path | Auth | Parameters/body | CLI equivalent | Notes |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `GET` | `/uniget/v1/packages/search` | Yes | Query `query`, optional `manager`, optional `maxResults` | `package search` | Search endpoint. |
|
||||
| `GET` | `/uniget/v1/packages/installed` | Yes | Optional query `manager` | `package installed` | Installed packages. |
|
||||
| `GET` | `/uniget/v1/packages/updates` | Yes | Optional query `manager` | `package updates` | Upgradable packages. |
|
||||
| `GET` | `/uniget/v1/packages/details` | Yes | Package action query set | `package details` | Details payload. |
|
||||
| `GET` | `/uniget/v1/packages/versions` | Yes | Package action query set | `package versions` | Installable versions. |
|
||||
| `GET` | `/uniget/v1/packages/ignored` | Yes | None | `package ignored list` | Ignored-update rules. |
|
||||
| `POST` | `/uniget/v1/packages/ignore` | Yes | Package action query set | `package ignored add` | Adds ignored-update rule. |
|
||||
| `POST` | `/uniget/v1/packages/unignore` | Yes | Package action query set | `package ignored remove` | Removes ignored-update rule. |
|
||||
| `POST` | `/uniget/v1/packages/download` | Yes | Package action query set | `package download` | Starts or performs download. |
|
||||
| `POST` | `/uniget/v1/packages/install` | Yes | Package action query set | `package install` | Starts or performs install. |
|
||||
| `POST` | `/uniget/v1/packages/reinstall` | Yes | Package action query set | `package reinstall` | Reinstalls package. |
|
||||
| `POST` | `/uniget/v1/packages/update` | Yes | Package action query set | `package update` | Updates one package. |
|
||||
| `POST` | `/uniget/v1/packages/uninstall` | Yes | Package action query set | `package uninstall` | Uninstalls package. |
|
||||
| `POST` | `/uniget/v1/packages/uninstall-then-reinstall` | Yes | Package action query set | `package repair` | Repair flow. |
|
||||
| `POST` | `/uniget/v1/packages/show` | Yes | Query `packageId`, `packageSource` | `package show` | UI-oriented package-details flow. |
|
||||
| `POST` | `/uniget/v1/packages/update-all` | Yes | None | `package update-all` | Requires `OnUpgradeAll` handler to be wired. |
|
||||
| `POST` | `/uniget/v1/packages/update-manager` | Yes | Query `manager` | `package update-manager` | Requires `OnUpgradeAllForManager` handler to be wired. |
|
||||
|
||||
## Headless-specific limitations
|
||||
|
||||
In headless sessions:
|
||||
|
||||
- `POST /uniget/v1/app/show` fails because there is no window to show.
|
||||
- `POST /uniget/v1/app/navigate` fails because there is no UI page stack to navigate.
|
||||
- `POST /uniget/v1/packages/update-all` fails unless a host wires `OnUpgradeAll`.
|
||||
- `POST /uniget/v1/packages/update-manager` fails unless a host wires `OnUpgradeAllForManager`.
|
||||
|
||||
These failures are intentional and surfaced as HTTP `400` with a descriptive message.
|
||||
|
||||
## Practical testing tip
|
||||
|
||||
If you want to inspect the IPC API manually with generic tools such as `curl`, the easiest route is to start UniGetUI in **TCP mode**:
|
||||
|
||||
```powershell
|
||||
UniGetUI.exe --headless --ipc-api-transport tcp --ipc-api-port 7058
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```powershell
|
||||
curl http://localhost:7058/uniget/v1/status
|
||||
```
|
||||
|
||||
For authenticated endpoints, you must also supply the session token as the `token` query parameter. The built-in CLI and `IpcClient` resolve that automatically.
|
||||
Reference in New Issue
Block a user