aim/README.md

upm

Universal Package Manager

upm is a Rust Cargo workspace for a modular package manager with a shared headless application core, thin frontend crates, and package-manager modules.

Workspace

• crates/upm-core: headless application layer for query normalization, orchestration, module registration and composition, registry persistence, install/update planning, and the unified frontend-facing API
• crates/upm: thin terminal frontend for argument parsing, config loading, prompting, progress reporting, and summary rendering
• crates/upm-appimage: AppImage package-manager module responsible for AppImage-specific acquisition and resolution behavior
• crates/upm-ui (planned): GUI frontend over upm-core

The split is intentional so future frontends can reuse upm-core, while package-manager behavior stays modular instead of being hardcoded into the core or the CLI.

Commands

upm <QUERY>
upm
upm update
upm list
upm search <QUERY>
upm remove <QUERY>

Query Forms

• owner/repo for GitHub shorthand
• appimagehub/<id> for AppImageHub shorthand
• GitHub repository URLs
• GitHub release URLs
• direct GitHub release asset URLs
• AppImageHub item URLs such as https://www.appimagehub.com/p/2338455
• https://... direct URLs
• GitLab URLs
• SourceForge URLs
• file://... local file imports

Search

upm search <QUERY> is part of the initial modular module surface.

• search is module-extensible and currently includes the built-in core search path plus AppImage-backed search sources
• search results should resolve to install-ready queries such as owner/repo and appimagehub/<id>
• module composition belongs in upm-core, not in the CLI frontend

Scope Overrides

By default upm auto-detects whether to use user or system scope. Override that with:

• --user
• --system

Config

Runtime config is loaded from ~/.config/upm/config.toml or $XDG_CONFIG_HOME/upm/config.toml.

Example:

allow_http = true

• allow_http = false is the default
• allow_http only permits user-supplied http:// inputs such as direct URL installs or updates from previously installed direct HTTP origins
• provider-resolved downloads such as AppImageHub artifacts remain HTTPS-only even when allow_http = true

Breaking Rename

• upm is a hard rename from aim
• runtime overrides now use UPM_* names such as UPM_CONFIG_PATH and UPM_REGISTRY_PATH
• old AIM_* runtime overrides are intentionally ignored
• default config and registry locations now live under upm paths

Current Flow Shape

• upm <QUERY> installs direct provider matches when available, otherwise falls back to search results, shows live progress on stderr, prints an Installation Summary on stdout for installs, and renders an Installation Review when tracking needs confirmation
• bare upm prints an Update Review without mutating the registry
• upm update executes the pending updates, streams live status on stderr, then prints an Update Summary
• upm list renders either Installed Apps or No installed apps yet
• upm remove <QUERY> resolves a registered application name, streams removal progress on stderr, then prints a Removal Summary

Terminal UX

• prompts use dialoguer
• styled summaries use console
• live spinners and byte progress use indicatif