upstream-rs 1.7.0

Fetch package updates directly from the source.
Documentation

Upstream

Upstream is a rootless package manager for installing software directly from release sources like GitHub, GitLab, and arbitrary download pages.

It fetches release assets, selects the best match for your system, and keeps them updated.

Features

  • Install from GitHub, GitLab, Gitea, direct URLs, or scraped pages
  • Automatic OS + architecture detection (Linux/macOS, x86_64/ARM)
  • Supports binaries, archives, AppImages, and compressed files
  • Rootless (user-level installs)
  • Track update channels: stable, preview, nightly
  • Flexible asset matching and filtering

Installation

Recommended (auto-install)

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

# Linux (Fish)
curl -fsSL https://raw.githubusercontent.com/what386/upstream-rs/main/scripts/install/install.fish | fish

# macOS
curl -fsSL https://raw.githubusercontent.com/what386/upstream-rs/main/scripts/install/install.zsh | zsh

# Windows (PowerShell)
iwr -useb https://raw.githubusercontent.com/what386/upstream-rs/main/scripts/install/install.ps1 | iex

This installs the binary, enables self-updates, and configures shell completion for the installer shell.

Install with Cargo

cargo install upstream-rs

Ensure Cargo bin is in PATH:

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

⚠️ Cargo installs do not support upstream upgrade self-updates.

Manual install

  1. Download a release from https://github.com/what386/upstream-rs/releases/latest
  2. Make it executable:
chmod +x upstream-rs

Optional: install upstream via itself:

./upstream-rs install upstream what386/upstream-rs -k binary

Quick Start

Initialize

upstream init

Install a package

upstream install mytool owner/repo

Example:

upstream install rg BurntSushi/ripgrep

Upgrade

upstream upgrade

Remove

upstream remove mytool

List

upstream list

Usage

Install

upstream install <name> <source> [options]
  • <name> → local alias
  • <source> → repo (owner/repo) or URL

Options:

  • --kind → asset type (auto, archive, binary, etc.)
  • --provider → github, gitlab, gitea, direct, scraper
  • --channel → stable, preview, nightly
  • --tag → specific version
  • --match-pattern / --exclude-pattern
  • --desktop → create launcher entry

Examples:

# GitHub install
upstream install fd sharkdp/fd

# Direct download
upstream install app https://example.com/app.tar.gz -p direct -k archive

# Scrape a page
upstream install tool https://example.com/downloads -p scraper

Upgrade

upstream upgrade [packages...] [--check] [--force]

Remove

upstream remove <packages...> [--purge]

Config

upstream config set key=value
upstream config get key
upstream config list
upstream config edit

Package management

upstream package pin <name>
upstream package unpin <name>
upstream package remove <name>
upstream package metadata <name>

Import / Export

upstream export file.json
upstream import file.json

Shell Completions

Download a completion file from releases or generate one.

Install automatically via helper scripts:

scripts/install/completions.sh bash
scripts/install/completions.sh fish
scripts/install/completions.sh zsh
scripts/install/completions.sh elvish

pwsh -File scripts/install/completions.ps1

Install

Bash

mkdir -p ~/.local/share/bash-completion/completions
cp upstream ~/.local/share/bash-completion/completions/

Fish

mkdir -p ~/.config/fish/completions
cp upstream.fish ~/.config/fish/completions/

Zsh

mkdir -p ~/.zfunc
cp _upstream ~/.zfunc/

Add to .zshrc if needed:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit

Architecture Detection

Upstream automatically selects assets based on:

  • OS: Linux, macOS
  • Arch: x86_64, ARM64

Selection is based on filename patterns and extensions.

Notes

  • Upstream installs packages in user space (no root required)
  • It does not manage system dependencies

License

MIT OR Apache-2.0