Upstream Package Manager

Upstream is a rootless, GitHub-centric package manager for Unix-like systems. It installs and updates software from releases, supports multiple asset types, tracks update channels, and automatically selects the best asset for your OS and CPU architecture.

Table of Contents

1. Features

2. Installation

   1. Auto Install (Recommended)
   2. Install via Cargo (Crates.io)
   3. Manual Installation (Linux)
   4. Manual Installation (MacOS)
   5. Build from Source

3. Usage

   1. Initialize Hooks
   2. Install a Package
   3. Remove Packages
   4. Upgrade Packages
   5. List Installed Packages
   6. Configuration Management
   7. View Package Info

4. Architecture Detection

Features

• Install packages directly from GitHub repository releases.
• Automatically detect system architecture (x86_64, ARM64) and OS (Linux, macOS).
• Supports binaries, archives, AppImages, and compressed files.
• Rootless, user-level installation.
• Track multiple update channels (stable, beta, nightly).

Installation

Auto Install (Recommended)

The easiest way to install Upstream is via the install script. This downloads the latest binary, sets it up in your user path, and enables self-updates.

curl -fsSL https://raw.githubusercontent.com/what386/upstream-rs/main/install.sh | bash

• Ensures Upstream can update itself automatically.

Install via Cargo (Crates.io)

Since Upstream is published on crates.io, you can install it directly with Cargo:

cargo install upstream-rs

• Cargo builds the binary and places it in $CARGO_HOME/bin (usually ~/.cargo/bin).
• Make sure this directory is in your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

• To update later:

cargo install --force upstream-rs

⚠️ Installing via Cargo does not enable self-updates via Upstream’s "upgrade" mechanism. Use the auto-install script for self-contained updates, or use cargo to update Upstream.

Manual Installation (Linux)

1. Download the latest release for your platform.
2. Ensure it is executable:

chmod +x path/to/upstream-rs

⚠️ Manual installation does not enable self-updates. To enable self-updates:

{path/to/upstream-rs} install what386/upstream-rs -k binary -n upstream

Manual Installation (MacOS)

MacOS support is experimental. Running Upstream on MacOS may work, but testing is limited. Please report any issues.

Build from Source

Requires Rust and Cargo:

git clone https://github.com/what386/upstream-rs.git
cd upstream-rs
cargo build --release

Executable location:

./target/release/upstream-rs

Manual builds do not enable self-updates.

Usage

All commands support --help:

upstream <command> --help

Initialize Hooks

upstream --init

• Hooks Upstream into your system’s PATH.
• Use upstream --clean to remove existing hooks.

Install a Package

upstream install <owner>/<repo> -k <type> -n <name> [--update-channel <channel>] [--create-entry]

Example:

upstream install foo/my-cool-app -k binary -n mytool --create-entry

• repo_slug → repository identifier (owner/repo).
• -k / --kind → asset type (binary, archive, appimage, compressed).
• -n / --name → local alias.
• -p / --provider → provider to source from (defaults to Github)
• --update-channel → track stable, beta, or nightly. (defaults to Stable)
• --create-entry → optional .desktop entry creation.

Remove Packages

upstream remove <package1> <package2> ... [--purge]

• Uninstall packages.
• --purge → remove configuration data. (currently does not work.)

Upgrade Packages

upstream upgrade [<package1> <package2> ...] [--force] [--check]

• Updates specified packages, or all if no names are given.
• --force → reinstall, even if up-to-date.
• --check → preview updates without applying them.

List Installed Packages

upstream list [<package>]

• No arguments → list all installed packages with metadata.
• With a package name → show detailed metadata for that package.

Configuration Management

upstream config <action> [options]

Available actions:

View Package Info

upstream info <package>

Shows metadata: install path, provider, asset type, update channel, last update, and more.

Architecture Detection

Upstream automatically detects OS and CPU:

• Linux → x86, ARM
• macOS → x86, ARM

It selects the best asset for your system based on filename patterns and extensions. If installs fail, please open an issue.