CONCEPTS

Profiles

A profile chooses what a machine gets. A "work" profile can have IDE configs that a "server" profile does not need. Each machine has one profile. A machine without one is in profile dev.

Machine profiles

Each profile has its own dotfiles, folders and package managers. Tether stores the dotfiles of a profile under profiles/<name>/ in the sync repo.

tether machines profile create work
tether machines profile create server --from work --managers brew,npm
tether machines profile set work      # on this machine
tether machines profile list
tether machines profile edit work

• In a terminal, profile create asks about each dotfile, folder and package manager. -y takes every default. --from copies a profile without questions. --managers sets its package managers
• A machine sets its own profile with profile set. To set another machine's profile, add --on <MACHINE>. That machine takes the profile on its next sync. See Fleet commands
• In a terminal, a sync offers dotfiles from other profiles that yours does not have

Packages per profile

Each package belongs to one or more profiles. A machine installs a synced package only when its own profile is one of them, and a trusted record lists the package. So a server does not get the desktop apps of your laptops.

• By default, a package belongs to the profiles of the machines whose trusted, signed records list it. This machine's own record counts too
• tether packages share <ID> --to <PROFILES> adds profiles. Machines in those profiles then install the package
• tether packages unshare <ID> --from <PROFILES> takes profiles off. Nothing is uninstalled. Machines keep any copy they have
• tether packages uninstall <ID> uninstalls the package on this machine. When other profiles share the package, it then takes this machine's profile off it. Other profiles keep it. When this profile is the only one, the profiles do not change. Other machines in this profile stop new installs of it, but keep any copy they have. If the uninstall fails, the profiles do not change
• uninstall does not remove Homebrew taps. A formula or cask from a tap brings its tap to the profiles that have it
• tether packages list --other-profiles lists the packages of other profiles that this machine does not install
• On the dashboard Packages tab, each package shows its profiles. Press t to pick them in a checklist. x uninstalls and leaves the other profiles enrolled
• A sync drops Inbox items for packages that leave this machine's profile

Tether keeps these choices in packages/profiles.toml in the sync repo. An entry in this file replaces the default for that package.

[profiles]
"npm:typescript" = ["dev", "server"]

• Each change starts from the remote branch, adds or removes only the profiles you named, and pushes. Changes from two machines both stay, also for the same package
• A change does not start while the sync repo has changes that are not pushed
• Anyone who can push can edit this file. A package still installs on its own only when a trusted, signed record lists it
• If packages/profiles.toml exists but Tether cannot read it, a sync installs no synced packages and warns. The daemon notifies once. share, unshare and uninstall stop with an error until you fix or delete the file

For a worked example, see Keep servers clean.

Profiles and machines on 1.x

• Only machines on 2.0 apply package profiles. A machine on 1.x installs the packages of every profile
• A 1.x machine before 1.13.2 can revert changes in config.toml, such as profile definitions. It cannot change the profile of a 2.0 machine, because each 2.0 machine keeps its own assignment
• So change profile definitions after the 1.x machines are on 1.13.2, or after they upgrade. See Machines on 1.x