Upstream Package Manager

Upstream is a rootless, GitHub-centric package manager designed to install and update software on Unix-like systems. It supports multiple asset types, tracks upstream releases, and automatically selects the best asset for your system architecture.

---

Features

• Install packages directly from GitHub repositories.
• Auto-detect system architecture (x86_64, ARM64) and OS (Linux, macOS).
• Supports multiple asset types: appimages, binaries, archives, scripts, compressed files.
• Track, install, update, pause (pin), and resume packages.
• Configurable providers and API tokens.
• Rootless, user-level installation.

---

Installation

Linux

1. Download the latest release for your platform
2. Move the file into ~/.local/bin/
3. (Optional) Rename it to upstream for convenience.

MacOS

(Coming soon — contribution welcome! I don't have a Mac, so I can't test MacOS. To my knowledge, it should work.)

Build from source

Clone the repository and build with .NET 9.0:

git clone https://github.com/what386/upstream.git
cd upstream
dotnet build -c Release

Or run the CLI tool:

dotnet run -- install github:sxyazi/yazi -t archive

---

Usage

Upstream provides a set of commands for installing, updating, managing, and inspecting packages. For detailed information on flags and options, run:

upstream <command> --help

Install a Package

upstream install <provider>:<owner>/<repo> [-t <type>] [-n <name>]

Installs a package from a supported provider (e.g., GitHub). Use -t to specify an asset type. Defaults to 'auto' if not provided. use -t to specify a custom name. Defaults to repo name if not provided.

---

Update Packages

upstream update [<package>]

Checks for newer releases. Run without arguments to check all packages.

upstream upgrade [<package>]

Installs updates discovered by update. Run without arguments to update all packages.

---

Remove or Reinstall

upstream remove <package>

Uninstalls a package.

upstream reinstall <package>

Removes and installs the package again based on its original source.

---

List Packages or Sources

upstream list packages
upstream list sources

Displays metadata about installed packages or their update sources.

---

Package Info

upstream info <package>

Shows install path, provider, asset type, last update, and other metadata.

---

Pin / Unpin Packages

upstream pause <package>

Pins a package to its current version (skips updates).

upstream resume <package>

Unpins a package and re-allows updates.

---

Configuration

upstream config update --key <key>=<value>

Updates configuration values such as API tokens.

---

Architecture Detection

Upstream automatically detects your OS and CPU architecture:

• Linux (x86 or ARM)
• macOS (x86 or ARM)

It selects the most appropriate release asset by matching filename patterns and extensions. If you encounter unusual filenames or any non-working installs, please open an issue.

---

Configuration

You can set provider-specific configuration keys such as API tokens:

upstream config update --key github.apiToken=xxx

Upstream uses tokens automatically when required. A GitHub token is optional but recommended to avoid rate limits.

---

Directory Structure

Metadata (installed package info, tracked repos, config) is stored in:

~/.config/upstream/

Installed packages live under:

~/upstream/
├─ appimages/
├─ binaries/
├─ archives/
├─ scripts/
└─ symlinks/

Symlinks are created for convenient access to installed executables.

---

Contributing

1. Fork the repository

2. Create a feature branch:

   git checkout -b feature/awesome-feature

3. Commit your changes

4. Push the branch

5. Open a pull request