Quick Start

This guide covers installation, first-time setup, and everyday usage of Tildr.

Prerequisites

RequirementMinimumNotes
OSLinux or macOSWindows is not currently supported
Git2.0+Optional but recommended for full functionality
GPG2.0+Required only for tildr secret commands
Rust1.90.0+Required only for building from source

Installation

Linux — script (any distro):

curl -fsSL https://orbitbits.com/tildr/linux.sh | sh

This script:

  • Detects your distribution and installs the appropriate package
  • Installs the Nautilus plugin if GNOME Files is detected
  • Installs the Dolphin plugin if KDE Dolphin is detected

macOS — script:

curl -fsSL https://orbitbits.com/tildr/macos.sh | sh

Debian / Ubuntu / Mint — apt repository:

# Import GPG key
curl -fsSL https://deb.orbitbits.com/tildr-deb-pub.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/tildr.gpg

# Add repository
echo "deb [signed-by=/usr/share/keyrings/tildr.gpg] https://deb.orbitbits.com/ stable main" \
  | sudo tee /etc/apt/sources.list.d/tildr.list

# Install
sudo apt update && sudo apt install tildr

Arch Linux — AUR (yay):

yay -S tildr-bin

Fedora / RHEL — RPM repository:

# Import GPG key
sudo rpm --import https://rpm.orbitbits.com/tildr-rpm-pub.gpg

# Add repository
sudo dnf config-manager addrepo \
  --from-repofile=https://rpm.orbitbits.com/tildr.repo

# Install
sudo dnf install tildr

From source (any platform):

cargo install tildr

Or clone and build:

git clone https://github.com/orbitbits/tildr.git
cd tildr
cargo build --release
# Binary at target/release/tildr

Verify Installation

tildr --version
tildr info credits

First Setup

Step 1 — Initialize

tildr init

This creates:

  • ~/.dotfiles/ — your Tildr repository
  • ~/.config/tildr/config.toml — your configuration file
  • A Git repository inside ~/.dotfiles/ (if Git is available)

Step 2 — Discover Files

tildr suggest

Tildr scans $HOME for common dotfile patterns (shell configs, editor configs, terminal emulators, git, etc.) and suggests files that could be managed.

Step 3 — Add Files

# Add individual files
tildr add .bashrc
tildr add .zshrc .gitconfig .tmux.conf

# Add a directory (traversed recursively)
tildr add .config/nvim

# Add multiple files at once
tildr add .bashrc .zshrc .gitconfig

Each add command:

  1. Moves the file from $HOME into ~/.dotfiles/
  2. Creates a symlink at the original location
  3. Auto-commits to Git (if git.auto_commit = true)

Step 4 — Check Status

tildr status

Shows the synchronization state of all managed files:

StatusMeaning
linkedSymlink exists and points to the correct repository file
missing_linkRepository file exists but the home symlink is absent
broken_symlinkA symlink exists but points to a wrong target
not_a_symlinkA regular file or directory exists where the symlink should be

Step 5 — Verify Setup

tildr doctor

Runs health checks on:

  • Repository existence
  • Config file validity
  • Git repository status
  • File permissions
  • Disk usage
  • Symlink correctness

Step 6 — Create Backup

tildr backup

Creates a .tar.gz archive of the entire repository at ~/.dotfiles-backup-YYYY-MM-DD.tar.gz.

Everyday Workflow

# Apply repository state to $HOME (repairs symlinks)
tildr apply

# Check for drift
tildr status

# View statistics about managed files
tildr stats

# See Git changes inside the repository
tildr git status

# Sync with a remote (bidirectional pull/push)
tildr sync

# Open the repository in your file manager
tildr open

Shell Aliases

Add these to your ~/.bashrc or ~/.zshrc for a smoother workflow:

# Jump to the Tildr repository
alias tcd='cd "$(tildr repo path)"'

# Quick status check
alias tstatus='tildr status --counter'

# Quick apply
alias tapply='tildr apply'

# Quick sync
alias tsync='tildr sync'

# Edit a managed file by name (no path needed)
alias tedit='tildr edit'

# Open the repository in your file manager
alias topen='tildr open'

These are suggestions — only add the ones you actually use. The key one is tcd, since a child process cannot change the parent shell’s directory, tildr repo cd is not possible, but cd "$(tildr repo path)" works perfectly as an alias.

Secret File Management

# Register a sensitive file
tildr secret add ~/.ssh/id_rsa

# List registered sensitive files
tildr secret list

# Manually re-encrypt
tildr secret encrypt

# Decrypt and restore sensitive files
tildr secret decrypt

Two encryption modes are available:

ModeConfigurationPassphrase Required
Symmetric (default)[crypto] mode = "symmetric"Yes — same passphrase for encrypt/decrypt
Asymmetric[crypto] mode = "asymmetric"No — uses GPG key pair

Batch Operations with Groups

# Create a group of related files
tildr group create dev --files .bashrc .zshrc .tmux.conf

# List all groups
tildr group list

# Apply all files in a group
tildr group apply dev

# Remove symlinks for all files in a group
tildr group unlink dev

Machine-specific Profiles

# Create a profile for work environment
tildr profile create work --description "Work laptop"

# Add files to the profile (copies to profiles/work/)
tildr profile add work --files .bashrc .ssh/config

# Create another profile
tildr profile create personal --description "Personal desktop"
tildr profile add personal --files .bashrc .gitconfig

# Activate a profile
tildr profile set work

# Apply uses the active profile
tildr apply

# Switch profiles
tildr profile set personal
tildr apply

# Deactivate (revert to defaults)
tildr profile unset
tildr apply

Recovery and Maintenance

# Check status and diagnose issues
tildr status
tildr doctor

# Repair broken symlinks
tildr apply

# Remove symlinks without deleting files
tildr unlink .config/nvim

# Move files back from repository to $HOME
tildr restore .bashrc

# Delete managed files permanently
tildr del .config/nvim --purge

Troubleshooting

Repository must be inside $HOME:

Tildr requires the repository to be inside your home directory. Move it:

mv ~/.dotfiles ~/dotfiles  # if it was outside $HOME

Symlinks are broken after moving the repository:

Run tildr apply to repair all symlinks:

tildr apply

GPG not found:

Install GPG for your platform:

# Debian/Ubuntu
sudo apt install gnupg

# Arch Linux
sudo pacman -S gnupg

# macOS
brew install gnupg

File already managed:

If a file is already managed by Tildr, running tildr add on it again is a no-op:

tildr add .bashrc    # First time — adds the file
tildr add .bashrc    # Second time — skipped (already managed)

Interactive picker not showing:

If the number of managed files is below core.search_threshold (default: 15), the picker shows the full list directly. If it exceeds the threshold, a search step appears first.

Auto-commit not working:

Check your config:

tildr cat config

Ensure [git] auto_commit = true is set. Also ensure Git is available and git.available = true.

Next Steps