Latest version: 0.1.0

Tildr

Declare your `$HOME`. Keep it reproducible.

Tildr is a Rust CLI that moves real files into a repository inside your home directory, then projects them back into place with symlinks. The result is a controlled, inspectable, Git-friendly home state.

Symlink-based Repo stays in $HOME Supports .tildrignore

Install Tildr Read Documentation Source Code

Git Repository-backed

Rust Native CLI

JSON Status output

Doctor Health checks

Repository Model

Real files live in the repository. Your home directory gets the symlinked applied state.

Same Filesystem

Tildr is designed to keep the repository inside your home directory on the same filesystem.

In-repo source of truth Manage files from a single canonical repository.

Status visibility Inspect linked, broken, missing, or conflicting entries.

Safe workflows Use --dry-run, unlink, restore, and del intentionally.

Git-native Auto-commit changes and push the repository with tildr sync.

How It Works

A practical repository for your home state.

Tildr does not invent a hidden state layer. It works directly on your home directory, the repository, and the symlinks between them.

Initialize the repository

Create a repository inside $HOME. Tildr can also initialize a Git repository for version tracking.

Add files from `$HOME`

tildr add moves files into the repository and replaces the originals with symlinks at the same paths.

Re-apply the declared state

tildr apply recreates missing links and repairs broken ones so your home directory converges back to the repository state.

Inspect, restore, or remove

Use status, doctor, unlink, restore, and del to inspect drift and control each lifecycle step.

Use a repository-level .tildrignore file to exclude artifacts, caches, and anything that should not be scanned as managed content.

Create alias tildr-repo='cd "$(tildr repo)"' on Linux to jump directly into the repository whenever you need to edit or review managed files.

Operational boundary

Tildr works on the same home filesystem model. Keep the repository under $HOME; it is not a workflow for copying managed files from your home directory to another disk.

CLI Capabilities

Focused operations, explicit outcomes.

Tildr keeps the command model small and sharp, so repository state and filesystem state stay understandable.

Add and link

tildr add moves files into the repository, creates the symlink back into $HOME, and can auto-commit the result.

Apply and repair

tildr apply restores the repository-backed shape of your home directory and can replace conflicting files with --force.

Status and diagnostics

Use status for detailed link states and doctor for repository, permission, Git, and symlink health checks.

Unlink without deleting

tildr unlink removes only the symlinks from $HOME. Repository data stays intact and can be re-applied later.

Restore ownership

tildr restore moves the real file back from the repository into $HOME and removes the symlink.

Git-integrated sync

tildr sync pushes the current repository branch to its remote, complementing the local auto-commit flow.

Install

Get the CLI, then start with six real commands.

Install from the official script or remove it cleanly later. The workflow below reflects the actual command set of Tildr.

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

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

# 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

# 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

tildr init

Initialize the repository and config file under your home directory.

tildr add .config/nvim

Move real files into the repository and create symlinks in place.

tildr status --counter

Summarize linked, missing, broken, and conflicting entries.

tildr apply --dry-run

Preview convergence before touching the live home directory.

tildr apply

Create or repair symlinks from the repository into $HOME.

tildr sync

Push the current repository branch to its configured Git remote.

Safer change control

Dry-run support is available on the destructive or state-changing commands that matter, including add, apply, unlink, restore, del, and sync.

Interactive targeting

Commands like cat, edit, unlink, restore, and del can open a picker when you omit the target.

Structured output when needed

tildr status --json gives you machine-friendly status output for scripts, wrappers, or higher-level automation.

Documentation

Keep the operational model close at hand.

Tildr is easiest to trust when the repository model, path rules, and command semantics stay visible.

Technical documentation

Read the full command reference, repository model, path rules, and operational constraints.

Releases

Browse published binaries, version history, and release notes on GitHub.

Changelog

Track behavior changes, improvements, and command-level evolution over time.

Why Tildr

Your home directory should be operationally boring.

When the repository is predictable, the links are inspectable, and recovery commands are explicit, your setup becomes something you can rebuild instead of something you have to remember.

Manual drift

Configs silently diverge across machines until nobody knows which version is the real one.

Opaque ownership

You lose track of whether a file is local, copied, linked, generated, or safe to replace.

Explicit recovery path

Tildr gives you separate tools for re-applying, unlinking, restoring, deleting, and inspecting state.

Install Tildr Read Docs

Declare your $HOME. Keep it reproducible.