REFERENCE

Configuration

The configuration lives in ~/.tether/config.toml. It syncs, encrypted, so all machines share it. A sync merges changes from two machines. See Config merge.

Terminal

tether config get packages.min_release_age_days
tether config set packages.brew.trusted_taps '["oven-sh/bun"]'
tether config edit

tether config set reads the value as TOML, so arrays work. It refuses a key that the config does not have. The dashboard Config tab edits the same settings.

Example

~/.tether/config.toml

[backend]
url = "git@github.com:you/dotfiles.git"

[security]
encrypt_dotfiles = true
scan_secrets = true

[dotfiles]
files = [".zshrc", ".gitconfig"]
dirs = [".config/nvim"]

[packages]
min_release_age_days = 7          # 0 turns the limit off
allow_scripts = ["esbuild"]       # packages that may run install scripts
auto_install_from_trusted = true  # false holds other machines' packages until you approve them

[packages.brew]
enabled = true
sync_casks = true
trusted_taps = ["oven-sh/bun"]    # taps outside homebrew/*

[packages.npm]
enabled = true

Keys

Key	Meaning
`backend.url`	Git repository URL of the personal sync repo
`security.encrypt_dotfiles`	Encrypt dotfiles with AES-256-GCM. Default true
`security.scan_secrets`	Scan team dotfiles for secrets. See Secret detection for the commands that scan. Default true
`dotfiles.files`	Dotfiles to sync
`dotfiles.dirs`	Folders to sync
`profiles.<name>.dotfiles`	Dotfiles of a profile. An entry can be a table with path and on_conflict
`profiles.<name>.dirs`	Folders of a profile
`profiles.<name>.packages`	Package managers of a profile, such as ["brew", "npm"]. Empty means all enabled managers
`machine_profiles`	The profile of each machine. Set it with tether machines profile set
`project_configs.enabled`	Sync project configs, such as .env files
`project_configs.search_paths`	Folders to search for projects
`project_configs.patterns`	File patterns to sync in each project
`packages.<manager>.enabled`	Sync this manager: brew, npm, pnpm, bun, gem or uv
`packages.min_release_age_days`	Install only releases at least this many days old. Default 7. 0 turns it off. Homebrew has no limit
`packages.allow_scripts`	npm, pnpm and bun packages that may run their install scripts
`packages.auto_install_from_trusted`	Install packages from trusted machine records without a question. Default true
`packages.brew.trusted_taps`	Homebrew taps outside homebrew/* that Tether may install from
`packages.brew.sync_casks`	Sync Homebrew casks. Tether never installs casks on Linux
`merge.command, merge.args`	The merge tool for conflicts. See Conflicts
`dashboard.theme`	Dashboard colors: auto, mocha, latte or ansi

Tether also writes keys that you do not edit: config_version, config_writer, and sync_versions for each manager, which 1.x builds need. A new config gets sync_versions = false, and an existing value stays.

Settings for one machine

~/.tether/local.toml holds settings for this machine only. Tether never syncs it. Its values override config.toml on this machine. It takes these keys:

~/.tether/local.toml

[packages]
min_release_age_days = 14

[merge]
command = "vimdiff"
args = ["{local}", "{remote}", "{merged}"]   # the default when args is missing

Feature toggles

Terminal

tether config features                   # list the toggles
tether config features enable <FEATURE>
tether config features disable <FEATURE>

Feature	Default	Meaning
`personal_dotfiles`	true	Sync personal dotfiles
`personal_packages`	true	Sync personal package manifests
`collab_secrets`	false	Share project secrets with GitHub collaborators

Example, team sync only:

Terminal

tether config features disable personal_dotfiles
tether config features disable personal_packages