CONCEPTS

Packages and versions

Tether syncs the global packages of Homebrew, npm, pnpm, bun, gem and uv. Turn a manager on or off in the config:

tether config set packages.brew.enabled true
tether config set packages.uv.enabled true

Manifests

The sync repo has one manifest per manager in manifests/. A manifest lists package names only, one per line, as 1.x writes them. So machines on 1.x read them as before.

typescript
eslint
prettier

Homebrew uses a Brewfile with formulae, casks and taps:

brew "ripgrep"
cask "visual-studio-code"

Tether does not install casks on Linux, or when packages.brew.sync_casks is false.

A sync merges into the manifests. It adds names only from this machine's record and the records it trusts. It keeps the lines of other machines. It removes a name only when no machine record in the repo lists that package. A line in a manifest grants no trust.

Versions

Versions live in the signed machine records, not in the manifests. Each record lists the installed version of each npm, pnpm, bun, uv and gem package.

• A version must be a concrete release: semver for npm, pnpm and bun, PEP 440 for uv, and a RubyGems version for gem. Tether drops a record entry with a dist-tag such as latest, or with a range
• When records differ, the newest version wins, by the rules of each ecosystem
• A sync installs the newest version that a trusted record lists, when it passes the package checks
• Without a trusted version, a package installs the newest release that passes the release-age limit
• Homebrew installs the current release. The Brewfile has no versions

Pre-release 2.0 builds wrote lines such as name@1.2.3. Tether still reads such a line as its name, and the next write drops the version.

Other OS

Machine records name their OS. When only machines on another OS list a version, this machine tries it first. If it fails, Tether holds the newest release that suits this machine in the Inbox as "other OS version". Approve it to install exactly that release.

Install, uninstall and upgrade

tether packages list                      # installed packages, with their profiles
tether packages install npm:typescript    # a package another machine lists
tether packages uninstall npm:typescript  # uninstall here
tether upgrade --dry-run                  # what an upgrade would change

• tether upgrade installs the newest release that the release-age limit allows. It never downgrades a package. It asks first
• tether rollback packages <MANAGER> <COMMIT> rolls npm, pnpm, bun, gem or uv back to a manifest commit. It does not support Homebrew
• A package that fails to install waits 24 hours before Tether tries it again. See Failed installs