tetherCLI
GitHub ↗
Documentation pages

REFERENCE

Commands

Run tether <command> --help for the options of each command. Every command takes -y. For -y, exit codes, --json, machine arguments and package ids, see Exit codes and -y.

tether / tether dashboard

Open the interactive dashboard. See Dashboard.

Terminal
tether

tether init

Set up Tether on this machine. It asks for the repository and the passphrase, runs the first sync, and installs the daemon. See Quick start.

Terminal
tether init [--repo <URL>] [--no-daemon] [--team-only]
  • --repo <URL>: the Git repository URL. Without it, Tether asks
  • --no-daemon: do not install the daemon
  • --team-only: skip personal dotfiles and packages, and use team sync only

tether sync

Sync now. See How sync works.

Terminal
tether sync [--dry-run] [--rediscover]
  • --dry-run: show what a sync would do. It ends with "Dry run: nothing changed"
  • --rediscover: ask again about file imports that you dismissed

In a terminal, tether sync asks about conflicts and about items in the Inbox. Without a terminal, it runs as the daemon does: it records conflicts for tether resolve and holds Inbox items. On macOS, a sync in a terminal also moves an installed daemon to ~/.tether/bin/tether.

tether status

Show the sync status, the daemon state, this machine's profile and the synced files. It counts the items in the Inbox and the files with conflicts. It names each machine that still runs 1.x.

Terminal
tether status [--json]

tether diff

Show differences between machines.

Terminal
tether diff [--machine <MACHINE>]

tether daemon

Control the background daemon.

Terminal
tether daemon start
tether daemon stop
tether daemon restart
tether daemon status
tether daemon logs [-f] [-n <LINES>]
tether daemon install
tether daemon uninstall
  • status: whether the daemon runs, whether its login service is installed, and the last sync and upgrade
  • logs: print the end of the daemon log. -n sets the number of lines (default 50). -f keeps printing lines as the daemon writes them
  • install: install the login service. On macOS, a launchd agent runs a copy of Tether at ~/.tether/bin/tether and follows upgrades by itself. On Linux, a systemd user service. See Linux and systemd
  • uninstall: remove the login service. On macOS, it also removes the copy

tether machines

List, show, trust and remove machines, and manage profiles. See Machine trust.

Terminal
tether machines list [--json]
tether machines show [MACHINE]
tether machines rename <NEW>
tether machines remove <MACHINE>
tether machines trust <MACHINE> [--fingerprint SHA256:...] [--on <MACHINES|all>]
tether machines untrust <MACHINE>
tether machines profile <set|unset|create|edit|list>
tether machines profile set <PROFILE> [--on <MACHINES|all>]
  • list: every machine with its profile, version, last sync, key fingerprint and trust. It marks machines on 1.x, and records that may be an old id of this machine
  • show [MACHINE]: one machine's profile, versions, record status, full key fingerprint and trust. Without a machine, it shows this machine
  • rename <NEW>: rename this machine. Tether signs its record again under the new id. Other machines must trust the new id. The form rename <OLD> <NEW> still works in 2.0 with a warning, and fails when OLD is not this machine
  • remove <MACHINE>: remove a machine record, and its trusted key on this machine. With -y, Tether removes it without a question and prints what it removed
  • trust <MACHINE> --fingerprint SHA256:...: trust a machine's signing key if its fingerprint matches. Without a fingerprint, Tether shows the current one and asks, in a terminal only. When the signed record is missing, it pulls the sync repo first
  • untrust <MACHINE>: stop trusting a machine's signing key
  • profile set <PROFILE>: assign a profile to this machine
  • --on <MACHINES|all> on trust and profile set: send a signed command, so those machines do it on their next sync. See Fleet commands
  • profile unset: remove the profile assignment of this machine
  • profile create <PROFILE> [--from <PROFILE>] [--managers <LIST>]: create a profile. See Profiles
  • profile edit <PROFILE>: edit a profile
  • profile list: list all profiles and assignments

tether packages

List, install, share and uninstall packages, and decide on the Inbox.

Terminal
tether packages list [--json] [--other-profiles]
tether packages install <ID> [--on <MACHINES|all>]
tether packages share <ID> --to <PROFILES>
tether packages unshare <ID> --from <PROFILES>
tether packages uninstall [ID] [--on <MACHINES|all>]   # alias: remove
tether packages inbox [--json]
tether packages approve <ID> [--expect <VERSION|TAP|KEY>] [--allow-signature-failed]
tether packages approve --all [--from <MACHINE>]
tether packages reject <ID> [--expect <VERSION|TAP|KEY>]
  • list: installed packages by manager, with the profiles of each and this machine's profile. It also shows failed installs. A bare tether packages lists too, but takes no flags
  • list --other-profiles: instead, the packages of other profiles that trusted machines list and this machine does not install
  • install <ID>: install a package that another machine lists, as the dashboard's Import does. OSV checks the release first. A package that waits in the Inbox needs approve instead
  • share <ID> --to <PROFILES>: add profiles to the package, so machines in those profiles install it. Separate profiles with commas
  • unshare <ID> --from <PROFILES>: take profiles off the package. Nothing is uninstalled
  • uninstall [ID]: uninstall the package here. When other profiles share the package, take this machine's profile off it. For a package that failed to install, it stops the retries on this machine. Without a package, pick packages in a terminal
  • install --on and uninstall --on: send a signed command, so those machines install or uninstall the package on their next sync. See Fleet commands
  • inbox: list the packages, taps and machine keys that wait for your approval, grouped by source machine and reason
  • approve <ID>: install the package, or trust the machine key. machine:<id> works as tether machines trust <id>
  • approve --all [--from <MACHINE>]: approve every package in the Inbox, or every package from one machine. It lists the packages and asks first. Without a terminal, it needs -y. It leaves machine keys, malicious packages, packages whose record fails its signature, and packages without a version or tap to name
  • --allow-signature-failed: approve a package whose record fails its signature, without a terminal. It needs --expect too. In a terminal, Tether asks instead
  • reject <ID>: stop offering that version, tap or key
  • --expect: the version, Homebrew tap or key fingerprint you reviewed, as packages inbox shows it. Required without a terminal. Tether refuses the decision when the item changed

Older forms still work: packages remove from 1.x, and approve <ID> <EXPECTED> without --expect from the 2.0 betas.

tether upgrade

Upgrade installed packages to the newest release that the release-age limit allows.

Terminal
tether upgrade [--dry-run]
  • Tether lists what it will change and asks first. Without a terminal, it needs -y
  • --dry-run lists what an upgrade would change, and which packages stay because the release-age limit allows only an older version
  • An upgrade never downgrades a package. It installs only a target newer than the installed version, at that exact version
  • Tether checks each npm, pnpm, bun, uv and gem target against OSV. A target with a MAL- advisory waits in the Inbox, and the installed version stays
  • Tether asks before it upgrades an older npm, pnpm or bun that cannot enforce the release-age limit. Without a terminal, or with -y, it skips that manager. gem does not ask: Tether picks each gem's release from its RubyGems publish time
  • Homebrew upgrades include only outdated packages from trusted taps. Tether does not run brew update

tether rollback

Roll back a package manager's installed packages to a manifest commit. The managers are npm, pnpm, bun, gem and uv. Homebrew is not supported.

Terminal
tether rollback packages <MANAGER> <COMMIT>

Tether lists each package and version it would install, and asks first. Without a terminal, it needs -y. A snapshot version other than the newest trusted version installs only when you confirm it in a terminal. -y does not confirm it. Packages that fail a check wait in the Inbox.

tether config

Manage configuration. See Configuration.

Terminal
tether config get <KEY>
tether config set <KEY> <VALUE>
tether config edit
tether config dotfiles
tether config features [enable|disable <FEATURE>]
  • get: read a value. Use nested keys such as packages.brew.enabled
  • set: set a value. Tether reads the value as TOML, so arrays work: '["azure/kubelogin"]'. A bare word stays a string. Tether refuses a key that the config does not have
  • edit: open the config in your editor. It needs a terminal
  • dotfiles: pick the files, folders and patterns that sync
  • features: list, enable or disable feature toggles

tether ignore

Manage secret scanning patterns, and files this machine keeps.

Terminal
# Patterns the secret scanner skips
tether ignore secrets add <PATTERN>
tether ignore secrets list
tether ignore secrets remove <PATTERN>

# Files this machine keeps: a sync does not overwrite them
tether ignore files add <FILE>
tether ignore files project <PROJECT> <PATH>
tether ignore files list
tether ignore files remove <FILE>      # sync the file again

The 1.x forms ignore add|list|remove and ignore dotfile|project|sync-list|sync-remove still work.

tether resolve

Resolve file conflicts: keep local, use remote, launch the merge tool, or skip. Without a file, it resolves all. See Conflicts.

Terminal
tether resolve [FILE]

tether unlock / tether lock

unlock decrypts the encryption key with your passphrase and caches it. lock clears the cached key. See Encryption.

Terminal
tether unlock
tether lock

tether history

Show the change history of a dotfile from the sync repo.

Terminal
tether history <FILE> [--limit <N>]   # default 20

tether restore

Restore files from a backup or from git history.

Terminal
tether restore list                          # list backups
tether restore file                          # pick a file and a backup
tether restore file <FILE> --from <TIMESTAMP>
tether restore git <FILE> [--commit <SHA>]   # a dotfile from git history

tether identity

Manage the age identity for team secrets.

Terminal
tether identity init     # make a new identity
tether identity show     # show your public key
tether identity unlock   # unlock with your passphrase
tether identity lock     # clear the cached key
tether identity reset    # make a new identity; destroys the old one

tether team

Manage team repositories, secrets, files and project secrets. See Teams and collab.

Terminal
tether team setup
tether team add <URL> [--name <NAME>]
tether team list
tether team switch <NAME>
tether team status
tether team enable | disable
tether team remove [NAME]

tether team orgs add | list | remove <ORG>

tether team secrets add-recipient <KEY> [--name <NAME>]
tether team secrets list-recipients
tether team secrets remove-recipient <NAME>
tether team secrets set <NAME> [--value <VALUE>]
tether team secrets get <NAME>
tether team secrets list
tether team secrets remove <NAME>

tether team files list
tether team files local-patterns
tether team files diff [FILE]
tether team files reset [FILE] [--all]
tether team files promote <FILE>
tether team files ignore <FILE>
tether team files unignore <FILE>

tether team projects add <FILE> [--project <PATH>]
tether team projects list
tether team projects remove <FILE> [--project <URL>]
tether team projects migrate
tether team projects purge-personal [--history]

tether collab

Share project secrets with GitHub collaborators. Needs the collab_secrets feature. See Collab secrets.

Terminal
tether collab init [--project <PATH>]
tether collab join <URL>
tether collab add <FILE> [--project <PATH>]
tether collab add-project <PATH>
tether collab refresh [--project <PATH>]
tether collab list
tether collab remove [NAME]