Tether CLI Documentation

Welcome to the Tether CLI documentation! Tether is an open source tool that automatically syncs your development environment (dotfiles and packages) across multiple Macs with end-to-end encryption.

Quick Start

Get up and running in under a minute:

bash 
# Install via Homebrew
$ brew install tether-cli

# Initialize with your Git repository
$ tether init --repo git@github.com:username/dotfiles.git

# Done! Tether is now syncing automatically
$

Key Features

  • Automatic Syncing: Background daemon watches for changes and syncs in real-time
  • End-to-End Encryption: AES-256-GCM encryption with keys in iCloud Keychain
  • Package Manager Support: Syncs Homebrew, npm, and pnpm global packages
  • Secret Detection: Prevents accidental syncing of API keys and credentials
  • Git-Backed: Full version history and rollback capabilities
  • Mac-Native: Optimized for macOS with system integrations

What Gets Synced?

Dotfiles (Encrypted)

  • .zshrc - Shell configuration
  • .gitconfig - Git settings
  • .zprofile - Shell profile (optional)
  • Custom dotfiles you specify

Package Managers

  • Homebrew: Formulae, casks, and taps (via Brewfile)
  • npm: Global packages
  • pnpm: Global packages

How It Works

Tether uses a Git repository as the sync backend. When you make changes to dotfiles or install packages, the background daemon detects these changes, encrypts your dotfiles with AES-256-GCM, and pushes them to your private Git repository. On your other machines, Tether pulls these changes and applies them automatically.

Encryption keys are stored securely in iCloud Keychain and automatically sync across your Macs. Your dotfiles are stored as .enc files in Git, so even if someone gains access to your repository, they cannot read your configurations without the encryption key.

Requirements

  • Platform: macOS 11.0 (Big Sur) or later
  • Shell: zsh (default on macOS)
  • Git: Configured with GitHub, GitLab, or self-hosted Git server
  • iCloud: Signed in for Keychain sync (for multi-machine setup)

Next Steps

Getting Help

If you run into issues or have questions: