IPC.md

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.
• 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:

/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:

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. Defaults to the download location configured in the settings, or to the user's Downloads folder

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, plus systemRestartPending and systemRestartPendingPackages (see Pending machine restarts).
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

Every operation payload carries systemRestartRequired: true when the operation succeeded but the machine must be restarted before the change takes effect. See Pending machine restarts.

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

Start Menu shortcuts

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. reset-all forgets every verdict; the folder rules and the relocations they recorded are left alone, and are managed by the folder endpoints below.

Method	Path	Auth	Parameters/body	CLI equivalent
GET	/uniget/v1/start-menu-shortcuts	Yes	None	start-menu shortcut list
POST	/uniget/v1/start-menu-shortcuts/set	Yes	Query path, status	start-menu shortcut set
POST	/uniget/v1/start-menu-shortcuts/reset	Yes	Query path	start-menu shortcut reset
POST	/uniget/v1/start-menu-shortcuts/reset-all	Yes	None	start-menu shortcut reset-all

Start Menu folders

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, manager\PackageId (for example winget\Python.Python.3.13); the manager segment is lower-cased. folder must be a subfolder of that directory, so an absolute path, a .. segment or the machine-wide directory is rejected. relocate-existing additionally moves the shortcuts that already match the package, which are listed as matchingShortcuts so a caller can inspect them first.

Method	Path	Auth	Parameters/body	CLI equivalent
GET	/uniget/v1/start-menu-folders	Yes	None	start-menu folder list
POST	/uniget/v1/start-menu-folders/set	Yes	Query package, folder, optional relocate-existing	start-menu folder set
POST	/uniget/v1/start-menu-folders/remove	Yes	Query package	start-menu folder remove

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

Every package payload carries systemRestartPending: true when that package is one of the packages this machine is waiting on a restart for. See Pending machine restarts.

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	Optional query manager	package update-all	Queues an update for every available update and returns their operation ids. See Updating everything.
POST	/uniget/v1/packages/update-manager	Yes	Query manager	package update-manager	Same as update-all with manager set.

Updating everything

update-all and update-manager queue one update operation per available update and return at once; they never wait for the updates themselves. They update what the Software Updates page lists, so ignored updates, skipped minor updates and the minimum update age apply, and a package that already has an update queued or running is skipped. If the update list has not been loaded yet, the request waits for that first load.

The response lists the operations it queued:

{
  "status": "success",
  "command": "update-all",
  "completed": false,
  "message": "The updates were queued for background execution.",
  "queuedCount": 2,
  "succeededCount": 0,
  "failedCount": 0,
  "results": [
    { "status": "success", "operationId": "…", "operationStatus": "inqueue", "completed": false, "package": { "id": "Git.Git", "manager": "winget" } }
  ]
}

Follow each one through /uniget/v1/operations/{operationId}, or let the CLI do it with package update-all --wait true. With no updates available, queuedCount is 0, completed is true and results is empty.

In a session with a window, the window queues the updates, so they also appear in its operations list. A headless session queues them itself.

Pending machine restarts

Some installers finish successfully but only take effect after the machine reboots (WinGet 0x8A150109/0x8A15010B, Chocolatey 3010/1641). UniGetUI records those packages and keeps the record until the machine has actually rebooted — closing and reopening UniGetUI does not clear it.

These fields expose it, so a fleet tool can tell which machines are waiting on a restart and why:

Payload	Field	Meaning
GET /uniget/v1/app	systemRestartPending	The machine is waiting on a restart.
GET /uniget/v1/app	systemRestartPendingPackages	How many packages are waiting on it.
Operation payloads	systemRestartRequired	This operation succeeded but needs a restart.
Operation-history entries	systemRestartRequired	Same, for a finished operation.
Package payloads	systemRestartPending	This package is waiting on a restart.

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.

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:

UniGetUI.exe --headless --ipc-api-transport tcp --ipc-api-port 7058

Then:

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.