Reference

External software

Windows keeps your configuration in files, the Registry, system APIs, and other locations. Applications and other software may keep their own settings in several of those places. Pinman tracks selected settings across these locations and uses its software catalog to identify the software that owns or uses them.

In Pinman, software is a broad term for applications, drivers, utilities, services, runtimes, and Windows tools. Each entry in the catalog represents a known application, tool, or component and gives it a stable identity. Thus, Pinman can associate tracked files and settings with a catalog entry even when they're stored in different places. Pinman can detect whether a given software is installed on your machine, and, when possible, let you open it via Pinman.

The catalog describes software; it does not install it, contain its configuration, or determine what Pinman tracks. This guide explains how catalog definitions become a Machine inventory and how that inventory relates to tracked configuration.

Why Pinman has a software catalog#

A file path or Registry key is not a reliable identity for software. Applications move, vendors rename them, several editions can share configuration, and one product can consist of multiple executables and tools. Pinman therefore gives relevant software a stable catalog ID.

That identity lets Pinman:

associate tracked items with the software that owns or uses them;
filter configuration and journal history by software;
detect whether known software is available on a particular machine;
record its detected version and installation path when those can be determined;
open the software or an associated Windows tool when a launch command is available;
associate useful tools with hardware categories such as displays or audio devices; and
provide named path anchors that schemas can use instead of repeating installation paths.

The catalog supplies context around configuration. It does not decide which files, Registry values, or system settings Pinman tracks; the schema still does that.

Definition and machine state#

Each catalog entry combines two kinds of information:

Layer	Describes	Examples
Catalog definition	What the software is and how Pinman can work with it	Stable ID, label, class, vendor, detection rules, launch command
Detected state	What the latest scan found on this machine	Installed or not found, version, installation directory, executable path, last seen time

Catalog definitions are registered when their schemas are imported. A software detection scan then updates the machine-specific fields on those existing records. Detection does not create a new catalog entry for an unfamiliar application.

This distinction is important: an entry can be known to Pinman without being found on the current machine. Conversely, software that is installed but has no catalog entry is outside this inventory.

Software identity#

Every catalog entry has a machine-readable name that acts as its stable ID and a label for people to read. For example:

windows:device_manager    Device Manager
nvidia:app                NVIDIA Utility
adobe:photoshop           Adobe Photoshop

Many IDs use group:member form. The part before the colon identifies a software family or vendor namespace; the part after it identifies a particular member. A catalog may also use a bare ID when it does not need members.

Group IDs are useful when several entries should be treated as one family. A filter for a group can match its group:* members, while a full ID selects one member. One member can be declared the group's default where Pinman needs a single representative.

The ID is an authoring contract. It should remain stable when a display label, executable name, version, or installation location changes.

Each entry also has a software_class, a broad role used to filter and group the software inventory. The built-in classes are application, service, driver, utility, runtime, and os_builtin; a Kit may add its own where its domain needs a finer distinction. A class describes an entry; it does not make it detectable or launchable.

Association with tracked configuration#

Schema items can carry one or more software IDs in software_refs. The association says that the item belongs to, configures, or is otherwise relevant to that software.

For example, a schema could associate an application's preferences file and Registry values with the same software ID even though they live in different realms. Pinman can then present and filter those items as one body of configuration. Capture notes and journal entries can also use software references, including references derived from changed tracked items.

An association does not make the catalog entry a schema item, and it does not broaden the schema. Pinman still reads only the locations and values the schema declares. Adding a software reference to a directory does not discover or track every setting used by that application.

For the authoring syntax and inheritance behavior, see software_refs: blocks.

Detect known software#

Run detection to compare the catalog with the current machine:

pinman software detect

The exact check belongs to each catalog entry. Depending on the software, Pinman can use:

Evidence	What Pinman checks
Windows uninstall record	A declared display name and any reported version or install location
Filesystem	A declared executable beneath a resolved installation directory
Registry	The presence of a declared key
Process	Whether a declared process name is currently running
Fixed command	A path, command, or short availability check associated with a launch command

A built-in Windows tool can be declared always available rather than requiring an installation check. If an executable is found, Pinman can also read its file version. An uninstall record may supply the version when file-version information is unavailable.

During detection, Pinman evaluates only known catalog entries and the evidence declared for them. It does not build a general inventory of every installed Windows application or search the whole disk for possible software. A positive result means that the entry's check succeeded; it does not prove that every component is installed, that the application is correctly configured, or that Pinman can read and write its settings.

The first complete scan establishes a baseline. Later scans can report entries that are newly found, no longer found, or found at a different version. Pinman records those changes in the journal. If a probe fails with an error, Pinman retains the previous state instead of treating the error as evidence that the software was removed.

Run detection again after installing, removing, upgrading, or moving relevant software, or after importing schemas that add catalog entries.

Inspect the software inventory#

By default, list shows catalog entries found by the latest detection scan:

pinman software list

Include known entries that were not found with --all, or filter by class:

pinman software list --all
pinman software list --class utility

Use show for one record. It accepts the catalog ID, displayed label, or numeric database ID:

pinman software show windows:device_manager

The web interface uses the same catalog and detected state for its software inventory.

Open external software#

A catalog entry can define a fixed launch command, such as a Windows settings URI or management console. An installed application can instead use the executable path resolved during detection. When either form is available, Pinman can open the software on the managed machine:

pinman software launch windows:device_manager

Launching is deliberately narrow. Pinman starts the command associated with the entry; it does not install the software, manage its updates, or take general control of its interface. Not every catalog entry is launchable.

Guided profile actions#

A Profile Apply can also use the catalog to launch software for guided actions. Some target settings cannot be changed directly through a supported adapter. For those settings, Pinman can group the manual actions by cataloged software, open the correct application or tool, and present the steps to follow. When Pinman can read the setting afterward, it can also verify the result.

The same guided workflow can be followed by a person or a computer-use agent.

Software path anchors#

A catalog definition can publish named paths for its schemas to reuse. A name such as EXAMPLE_APP_ROOT can represent the application's root directory while schema items build locations beneath it. This gives related schemas one path contract instead of copying the same literal location throughout their definitions.

Path anchors help schemas locate configuration; they do not cause Pinman to track the directory or its contents. Tracking still requires declared schema items. See software path anchors for authoring details.

What the catalog does not represent#

The software catalog is not:

a complete list of software installed in Windows;
a package manager, installer, or update service;
a list of currently running processes;
a substitute for the schema that declares tracked configuration; or
a copy of an application's files, binaries, or settings.

Where catalog definitions come from#

Pinman's built-in Windows definitions live in data/platform/windows/catalog/:

File	Definitions
`core_os.yaml`	Device Manager, display and sound settings, Power Options, and Disk Management
`core_gpu.yaml`	AMD Adrenalin and ASUS Armoury Crate
`core_nvidia.yaml`	NVIDIA App and NVIDIA Control Panel

Additional definitions can arrive with a Kit when that Kit's schema is imported into a project. This page describes the resulting software model; the package and YAML mechanics belong to the Kit and schema guides: