installs

01 Commands

A bare installs prints the user-facing inventory. On ls, a query narrows that table. On search, install, and uninstall, the query is a name a person would type, such as firefox or ripgrep. A URL is rejected.

installs [query]

The inventory table. Same as installs ls. The query is optional.

installs ls [query]

Name, version, kind, source, and scope. A query is a case-insensitive substring of the name, id, command names, and bundle or package ids.

installs stats

Counts that same selection. Apps by source, then the whole selection by source and by kind. No name argument. The listing flags apply, including --all and --json.

installs show <query>

One record and every sighting that merged into it. When versions disagree, the report shows the disagreement.

installs sources

Collector health. Each source is ok, empty, skipped, denied, or failed. A manager that is not on the machine is skipped.

installs search <query>

Install methods discovery found. Does not change the machine. --manager keeps one manager.

installs install <query>

Asks, then runs one manager that is already on the machine. The query is a name, not a URL.

installs uninstall <query>

Matches an installed record, asks, and runs that record's package manager.

Listing flags

Shared by installs, ls, stats, show, and sources.

--all

Every kind the collectors gathered, including software that shipped with the OS, dependencies, and frameworks.

--kind

app, cli, library, runtime, plugin, font, driver, meta, other. Comma-separated.

--source

Only sightings from those collectors, after dedupe. Example: brew,apt.

--scope

user, system, or unknown.

--stale

Records whose files are gone but whose database entry remains.

--volumes

Other local volumes. The default is the boot volume only.

--include-envs

Conda, pyenv, and similar environments beyond the base or global one.

--all-users

Other users' homes and all-users stores, when this process can read them.

--json

The same selection as the human view, plus source health and the hidden counts. On stats, the counts as JSON.

Install flags

--manager

Only candidates from that manager. With --id, this is the non-interactive choice.

--id

Catalog id. Valid only with --manager, and only if discovery returned that pair.

--yes

Skip the confirmation when exactly one exact candidate exists, or when --manager and --id select one. Several candidates and --yes alone is an error.

--dry-run

Print the argv. Do not spawn it.

--reinstall

Continue even when the inventory already has this package from this manager.

Uninstall flags

--yes

Skip the confirmation when exactly one installed record was selected.

--dry-run

Print the argv. Do not spawn it.

02 Default view

The default view is what a person would name: apps they added, tools they asked for, distro packages they asked for that ship a command, and a few add-ons such as Rosetta, the Xcode Command Line Tools, a WSL distro, or a JDK or Node from a version manager.

Software that shipped with the operating system stays hidden. That includes macOS apps under /System and /System/Applications, and inbox apps such as Mail, Safari, Notes, Terminal, and Preview when the path or receipt says they shipped with the OS. Libraries, transitive dependencies, Flatpak runtimes, Snap bases, and Windows update entries stay hidden too. On Debian and Ubuntu, priority required, important, and standard stay with that base set.

--all shows the omitted set: preinstalled OS apps, dependencies, libraries, frameworks, plugins, fonts, and drivers. It does not crawl project trees (node_modules, .venv, vendor, target), it does not list the Nix or Guix store, and it does not cross onto other disks.

The table columns are name, version, kind, source, and scope. It ends with how many records were omitted and the flag that shows them. A Mac App Store app stays when it cannot be told apart from one the person added. Homebrew, npm, PATH tools the person added, and dragged-in apps stay. The same name from two sources is two rows.

installs sources ends with one summary line: how many collectors are ok, empty, skipped, denied, and failed. A missing manager is a skip. Inside a container, the inventory is the container. On WSL, it is the Linux distro. From Windows, a WSL distro is one runtime record.

03 Install and uninstall

installs search prints candidates and stops. installs install uses the same discovery. Both ask package managers that are already on the machine, confirm Repology names with those managers, and on a Mac also search the App Store. Install spawns the chosen manager with the id it returned.

When several exact methods exist, install prints a numbered list. No row is preselected. The person types a number or q. One exact candidate still asks, and the default is no:

Install <name> with <manager> (<argv>)? [y/N]

After a number, it asks again with that argv, unless --yes applies. --dry-run prints the argv and does not spawn it. The program does not refresh indexes, install a manager that is missing, or download a DMG, EXE, or AppImage itself.

If nothing matches exactly, partial names are shown and labeled partial. There is no default. Zero matches stop, and the command says which managers were queried and which are not on the machine.

installs uninstall matches a record already in the inventory, asks, and spawns that record's package manager. Several matches have no default. One match still asks. A filesystem or PATH-only record is refused. Uninstall does not delete an .app or a binary, and it does not install or remove a package manager.

A listing run does not call sudo. When apt, dnf, or pacman needs root, the confirmation shows sudo in the argv before anyone says yes.

04 Stats

installs stats counts the same selection as installs ls. Apps are counted on their own, with a share of the app total, then everything in the selection is counted by source and by kind. --all changes the selection, so it changes the counts. The default selection hides software that shipped with the OS.

Apps by source
SOURCE  COUNT  SHARE
brew  12  35%
flatpak  9  26%
apt  8  24%
snap  5  15%

Most apps: brew (12 of 34)

Everything by source
SOURCE  COUNT
brew  26
apt  14
flatpak  9
cargo  7
npm  5
snap  5
pipx  3
mise  2

Everything by kind
KIND  COUNT
cli  35
app  34
runtime  2

05 Limits

• It does not run a discovered program to ask for --version, --help, or anything that might open a window or wait on input. A version comes from a manager record, a manifest, or embedded build info. go version -m reads the file. It does not execute it. Asking brew, npm, or pip is asking a manager, not the installed tool.
• It is not install(1). It does not replace apt, brew, or winget. It hands those tools an id.
• It does not read documents, mail, browser history, or credentials. A listing run does not ask for a password.
• There is no upgrade command and no pin command.