upstream-rs 1.18.1

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
  • Dry-run previews for install, build, upgrade, remove, rollback, and reinstall workflows
  • Optional checksum and signature verification modes

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 hooks init

Install a package

upstream install mytool owner/repo

Example:

upstream install rg BurntSushi/ripgrep

Search and inspect sources

upstream search ripgrep
upstream probe 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 → override auto-detection (github, gitlab, gitea, direct, scraper)
  • --channel → stable, preview, nightly
  • --tag → specific version
  • --match-pattern / --exclude-pattern
  • --desktop → create launcher entry
  • --yes → accept the recommended discovered asset without prompting
  • --dry-run → preview resolution without downloading or writing files
  • --trust → verification mode (none, best-effort, checksum, signature, all)

Examples:

# GitHub install
upstream install fd sharkdp/fd

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

# Download assets from a download page
upstream install tool https://example.com/downloads

Archives that contain platform-specific subdirectories are resolved automatically. Use --match-pattern or --exclude-pattern to steer selection when an archive ships multiple compatible payloads.

Upgrade

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

Use --check --machine-readable for script-friendly update checks.

Search and Probe

upstream search <query> [--limit 20]
upstream probe <source> [--channel stable] [--verbose]

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

Upstream automatically installs package completion scripts for detected local shells when a release includes matching bash, fish, or zsh files such as <name>.fish, completions.bash, or completions/*.zsh. Archives and AppImages are scanned after extraction.

Download upstream's own 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