Command Reference

[!TIP] The add, restore, and unlink commands accept multiple file parameters simultaneously.

tildr add .config/nvim/init.vim .config/nvim/lua/plugins.lua
tildr restore .config/nvim/init.vim .config/nvim/lua/plugins.lua
tildr unlink .config/nvim/init.vim .config/nvim/lua/plugins.lua

If a path contains spaces, use single or double quotes:

tildr unlink '.config/my app/config.toml' .config/nvim/init.vim

Path Input

Commands that receive files accept several equivalent HOME-based paths:

tildr add .config/starship.toml
tildr add ~/.config/starship.toml
tildr add $HOME/.config/starship.toml

Absolute paths inside $HOME also work. When your current directory is inside $HOME, relative paths are resolved from that directory when possible:

cd ~/Documents
tildr add document.ods
tildr restore document.ods

The commands above are treated like ~/Documents/document.ods. This applies to managed-file commands such as add, restore, unlink, cat, edit, del, mv, and profile add/mv -f.

tildr init

Initializes the Tildr repository and writes the user configuration file.

tildr init
tildr init --repo ~/.dotfiles-work
tildr init --no-git
tildr init --force
tildr init --quiet

Options:

Behavior:

• Creates the repository directory
• Writes ~/.config/tildr/config.toml
• Detects whether Git is available in PATH
• Writes [git].available to the config
• Initializes a Git repository only when Git is available and --no-git is not used
• Refuses $HOME itself as the repository root
• Refuses repositories outside $HOME
• If already initialized and --force is not passed, refreshes the saved Git availability state

tildr import

Clone a remote dotfiles repository and apply it.

tildr import https://github.com/user/dotfiles
tildr import https://github.com/user/dotfiles ~/.dotfiles
tildr import https://github.com/user/dotfiles --force

Options:

Behavior:

• Clones the Git repository to the specified destination (or ~/.dotfiles)
• Creates or updates ~/.config/tildr/config.toml with the repository path
• Automatically runs apply to establish symlinks
• Destination must be inside $HOME
• Refuses to overwrite a config pointing to a different repository unless --force is used

tildr add

Adds a file or a directory tree from $HOME into the repository and replaces each file with a symlink.

tildr add .bashrc
tildr add .config/nvim
tildr add ~/.config/starship.toml
tildr add $HOME/.config/starship.toml
tildr add .config/nvim/init.lua --dry-run
tildr add .bashrc .config/nvim/init.lua
tildr add .config/app01.json --nolink

Options:

Behavior:

• If no path is passed, Tildr opens a file picker to select a file from $HOME
• Files are moved into the repository
• Symlinks are created at the original home path
• With --nolink, files are moved but no symlink is created and the file is added to .tildrignore
• Directories are traversed recursively
• Paths matched by .tildrignore are skipped
• Already-correct symlinks are skipped silently
• Existing sources in the target profile are preserved unless --force is used
• Adding to an inactive profile stores the variant but keeps $HOME aligned with the active profile
• If git.auto_commit = true, the repository is auto-committed after a successful run

tildr apply

Applies repository state into $HOME by creating or repairing symlinks.

tildr apply
tildr apply --check
tildr apply --dry-run
tildr apply --force --verbose

Options:

Behavior:

• Creates missing symlinks for all files effective for the active profile
• Repairs broken or incorrect symlinks automatically
• Removes Tildr-owned symlinks for files that exist only in inactive profiles
• Skips regular files already present in $HOME unless --force is used
• With --check, only validates symlinks and reports missing, broken, conflicting, or unexpected HOME links
• Uses the repository as the source of truth
• Does not modify repository content

tildr clean

Removes empty directories left inside profile storage.

tildr clean
tildr clean --dry-run
tildr clean --quiet

Options:

Behavior:

• Removes empty directories under common/ and profiles/<name>/
• Keeps structural directories such as common/, profiles/, and profile roots
• Does not remove files or symlinks
• Runs automatically after tildr profile mv

tildr status

Shows the synchronization state of files effective for the active profile.

tildr status
tildr status --json
tildr status --counter
tildr status --less

Output example:

PROFILE     FILEPATH            STATUS
no profile  ~/.zshrc            ✔ linked
no profile  ~/Templates/main.sh  ✔ linked
linux       ~/.bashrc           ✔ linked

The table output always includes the PROFILE column. Without --profile, Tildr shows the effective variant for each logical file. By default FILEPATH is the home-relative path you can pass to commands such as restore, unlink, cat, and del; use list --source or source-path to inspect repository source files. Shared files stored in common/ are shown as no profile in human-readable tables.

Options:

Status values:

The --counter mode prints a summary like:

Managed: 12
Linked: 10
Missing: 1
Broken: 0
Not symlink: 1

tildr list

Lists managed files as HOME paths.

tildr list
tildr list --long
tildr list --source
tildr list --tree
tildr list --less
tildr list --export ~/tildr-files.json
tildr list --import ~/tildr-files.json

Output example (default):

PROFILE     FILEPATH
no profile  ~/.zshrc
no profile  ~/Templates/main.sh
linux       ~/.bashrc

Output example (--long):

PROFILE     FILEPATH            TYPE  SIZE
no profile  ~/.zshrc            file  2.1 KiB
no profile  ~/Templates/main.sh  file  892 B
linux       ~/.bashrc           file  3.4 KiB

Output example (--source):

PROFILE     PATH
no profile  ~/.dotfiles/common/.zshrc
linux       ~/.dotfiles/profiles/linux/.bashrc

Options:

-t, –tree

Show the repository as a directory tree.

-l, –long

Show profile, HOME path, type and file size for each entry.

–source

Show repository source paths instead of HOME paths.

–less

View the output in an interactive pager (uses $PAGER or less -RFX).

–export <FILE>

Export the effective managed files as logical HOME-relative paths. With --profile, exports that profile’s paths instead.

–import <FILE>

Import a previously exported JSON file and create symlinks using the current active profile. Correct links and regular-file conflicts are preserved; files without an effective source are reported as warnings. Older exports containing common/ or profiles/<name>/ paths remain supported.

Export JSON format:

{
  "version": 1,
  "files": [
    ".bashrc",
    ".config/starship.toml",
    ".config/nvim/init.lua"
  ]
}

Notes:

• FILEPATH is always the HOME path, for example ~/.bashrc
• no profile means the source file is stored in common/
• Commands that manipulate files should use the logical path: tildr restore .bashrc
• Use --profile to target a variant explicitly: tildr restore .bashrc --profile linux, tildr del .bashrc --profile no-profile, or tildr cat .bashrc --profile linux
• Use tildr list --source to inspect all repository source paths
• Use tildr source-path <file> to inspect the repository source path for one file
• Export files always contain logical paths and never expose the storage hierarchy
• Tree view prints the managed HOME path tree
• .tildrignore patterns and internally excluded files are not shown

tildr source-path

Prints the repository source path for one managed HOME file.

tildr source-path ~/.bash_profile
tildr source-path .bashrc --profile linux

Output example:

~/.dotfiles/profiles/linux/.bash_profile

Options:

tildr repo path

Prints the absolute path to the configured Tildr repository.

tildr repo path

Useful for shell automation and aliases:

alias tildr-repo='cd "$(tildr repo path)"'

After that, tildr-repo takes you directly to the repository.

tildr git status

Runs git status scoped to the Tildr repository.

tildr git status

Behavior:

• Uses the configured repository as both --git-dir and --work-tree
• Prints a success message when the repository is clean
• Prints an informational message plus the normal git status output when there are tracked or untracked changes

tildr cat

Prints the content of a managed file from the repository.

tildr cat .bashrc
tildr cat .bashrc --profile linux
tildr cat .config/nvim/init.lua --less
tildr cat config
tildr cat

Options:

Behavior:

• If no target is passed, Tildr opens an interactive picker
• The special target config resolves to the Tildr config file itself
• Use --profile <NAME> to read a variant without switching the active profile
• When --less is used, Tildr respects $PAGER and falls back to less -RFX on TTY output

You can use your preferred file viewers by using the PAGER environment variable like this:

PAGER=bat tildr cat --less

tildr edit

Opens a managed file in the repository with the configured editor.

tildr edit .bashrc
tildr edit .bashrc --profile linux
tildr edit

Options:

Behavior:

• If no target is passed, Tildr opens an interactive picker
• Editor resolution order: $EDITOR → $VISUAL → nano
• Edits are made directly in the repository file; the symlink in $HOME reflects the change immediately

You can open it with your preferred editor using the EDITOR environment variable like this:

EDITOR=vim tildr edit .bashrc

tildr unlink

Removes symlinks from $HOME without touching the repository content.

tildr unlink .bashrc
tildr unlink .config/nvim
tildr unlink .bashrc .config/nvim/init.lua
tildr unlink --all

Options:

Behavior:

• Only symlinks in $HOME are removed
• Repository files remain untouched
• Directory targets are expanded recursively using active-profile variants with no-profile fallbacks
• Use --profile <NAME> to operate recursively on a specific profile instead
• Confirms before acting on a directory target unless --force is passed
• Empty parent directories in $HOME are cleaned up when possible
• If no target is passed, Tildr opens an interactive picker

tildr restore

Moves managed files back from the repository into $HOME and removes the symlinks.

tildr restore .bashrc
tildr restore .config/nvim
tildr restore .bashrc .config/nvim/init.lua
tildr restore --all

Options:

Behavior:

• Removes the home symlink if present
• Moves the real file back from the repository into $HOME
• Removes empty directories from the repository after restoration
• Directory targets and --all select active-profile variants with no-profile fallbacks
• Use --profile <NAME> to restore recursively from a specific profile instead
• Confirms before acting on a directory target unless --force is passed
• If no target is passed, Tildr opens an interactive picker
• Auto-commits the repository when git.auto_commit = true

tildr del

Deletes managed files from the repository and unlinks them from $HOME.

tildr del .bashrc
tildr del .config/nvim
tildr del --all
tildr del .bashrc --purge

Options:

Behavior:

• Removes the symlink from $HOME if it exists
• Deletes the file from the repository
• Default mode tries to send files to the system trash
• --purge permanently removes repository files without trash
• Confirms before acting on a directory target unless --force is passed
• If no target is passed, Tildr opens an interactive picker
• Auto-commits the repository when git.auto_commit = true

tildr sync

Synchronizes the repository with its configured Git remote in both directions.

tildr sync
tildr sync --dry-run
tildr sync --force

Options:

Behavior:

• Uses the current branch dynamically
• Uses the branch tracking remote and upstream branch from Git config
• Fetches from the tracked remote before deciding what to do
• If only local commits exist, pushes them
• If only remote commits exist, performs a fast-forward pull
• If both local and remote commits exist, simulates a merge first
• Reapplies the effective profile after pulls and merges so new, moved, or removed files are reconciled in $HOME
• Aborts safely and reports conflicting files when a merge conflict would occur
• Uses the saved Git availability from Tildr config instead of probing PATH on every run

tildr doctor

Runs a health check against the Tildr environment and reports any issues found.

tildr doctor

Checks performed:

Output example:

Checking environment...

✓ Repository    OK
✓ Config        OK
✓ Git           OK
✓ Permissions   OK
✓ Disk          OK (42.3 KB)
✓ Symlinks      OK

All checks passed

tildr completions

Generate shell completion scripts for various shells.

tildr completions bash
tildr completions zsh
tildr completions fish

Argument:

The shell to generate completions for: bash, zsh, fish, powershell, or elvish.

Installation:

Bash:

tildr completions bash >> ~/.bash_completion

Zsh (Oh My Zsh):

tildr completions zsh > ~/.oh-my-zsh/completions/_tildr

Zsh (vanilla):

Add the following to ~/.zshrc:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit

Then install the completions:

tildr completions zsh > ~/.zfunc/_tildr

Finally, restart your shell or run exec zsh for the changes to take effect.

Fish:

tildr completions fish > ~/.config/fish/completions/tildr.fish

Behavior:

• Generates and outputs shell-specific completion scripts
• No interactive installation — output is printed to stdout for you to redirect or pipe
• Each shell has its own completion script format and installation location

tildr mv

Renames or moves a managed file inside the repository and updates its symlink in $HOME. Mirrors the behavior of the Linux mv command — rename and move are the same operation.

tildr mv .bashrc .bashrc_backup
tildr mv ~/.yarnrc ~/.yarnrc.bak
tildr mv $HOME/.yarnrc $HOME/.yarnrc.bak
tildr mv files/file.txt configs/file.txt
tildr mv

Options:

Behavior:

• Renames or moves the file inside the repository
• Removes the old symlink from $HOME
• Creates a new symlink at the new path in $HOME
• Source and destination are logical $HOME paths; do not include common/ or profiles/<name>/
• Removes empty source directories left in profile storage
• .bak is a valid managed suffix; use .tildrignore when backup files should be excluded
• If the destination is a filename only (no directory), the original directory is preserved
• If no arguments are passed, Tildr opens an interactive picker to select the source, then prompts for the new path
• Auto-commits the repository when git.auto_commit = true

tildr exclude

Manages patterns in .tildrignore without editing the file manually.

tildr exclude add *.log
tildr exclude add cache/
tildr exclude rm *.log
tildr exclude list

Options:

Behavior:

• Creates .tildrignore if it does not exist
• Duplicate patterns are ignored when adding
• Fails if the pattern is not found when removing
• Patterns use gitignore-style matching semantics
• Patterns added here prevent files from being discovered by list, status, and apply
• Does not remove existing symlinks — use tildr unlink for that

tildr open

Opens the Tildr repository in the configured or system file manager.

tildr open

Behavior:

• Launches the repository path in the configured file manager when core.file_manager is set
• Falls back to the system default file manager when core.file_manager is empty or unset
• Uses the open crate for cross-platform fallback support (xdg-open on Linux, open on macOS)

Example configuration:

[core]
file_manager = "nautilus"

tildr stats

Shows statistics about managed files.

tildr stats

Output example:

Managed files: 47
Total size:    2.3 MB
Largest:       .config/nvim/init.lua (12.4 KB)
By extension:  .toml (12), .lua (8), .sh (6), .json (5)

Behavior:

• Counts total managed files
• Calculates total size of managed files in $HOME
• Shows the largest managed file
• Shows file extension distribution (top 6)

tildr backup

Creates a compressed tarball backup of the repository.

tildr backup
tildr backup --output ~/my-backup.tar.gz

Options:

Behavior:

• Creates a .tar.gz archive of the entire repository
• Default output: ~/.dotfiles-backup-YYYY-MM-DD.tar.gz
• Shows the backup file size after creation
• Requires tar to be installed on the system

tildr suggest

Scans $HOME for common dotfile patterns that could be managed by Tildr.

tildr suggest

Output example:

Suggested files in $HOME:

  Shell:        .zshrc, .bash_profile
  Editor:       .config/nvim/init.lua
  Terminal:     .config/alacritty.toml
  Git:          .gitconfig
  Tools:        .tmux.conf

Run `tildr add <file>` to manage them.

Behavior:

• Checks for common dotfile patterns (shell configs, editor configs, terminal emulators, git, etc.)
• Skips files already managed by Tildr
• Reports suggestions grouped by category
• Does not modify any files

tildr snapshot

Generate a reproducible bootstrap script from the current Tildr setup.

tildr snapshot > setup.sh
tildr snapshot --output ~/setup.sh
chmod +x setup.sh
./setup.sh

Options:

–output <FILE>

Custom output file path. If omitted, prints to stdout.

Behavior:

• Generates a shell script that reproduces the entire Tildr setup on a new machine
• Auto-detects the git remote URL for the clone step
• Checks prerequisites (git, tildr, optionally gpg)
• Preserves the configured repository location relative to $HOME
• Clones the repository or creates it if it doesn’t exist
• Initializes or updates Tildr config to point at that exact destination
• Runs tildr apply to create symlinks
• Decrypts secrets if .tildr/encrypted.gpg exists
• Output is idempotent — safe to run multiple times

tildr group

Manages named groups of managed files for batch operations.

tildr group list
tildr group create dev --files .bashrc .config/nvim
tildr group add dev --files .tmux.conf
tildr group add term --files .term
tildr group rm dev --files .tmux.conf
tildr group rm term --files .term
tildr group rename dev shell
tildr group delete dev
tildr group apply dev
tildr group unlink dev

Groups store logical HOME-relative paths. Existing groups.json entries using legacy common/, profiles/<name>/, ~, or $HOME paths are normalized when loaded and saved in logical form on the next group mutation.

Options:

Behavior:

• Groups are stored in .tildr/groups.json in the repository root
• Groups store logical $HOME paths, such as .bashrc or .config/nvim/init.lua
• --files accepts $HOME paths, ~, $HOME, cwd-relative paths, common/<path>, and profiles/<name>/<path>
• --files accepts both files and folders; folders are expanded recursively
• add with a folder adds all files inside it (e.g. --files .term adds .term/*.sh, etc.)
• rm with a folder removes all entries that start with that path (e.g. --files .term removes .term/behavior.sh, .term/colors.sh, etc.)
• rename preserves the group’s file list and only changes the group name
• When no --files is provided, add opens a file picker in the repository
• apply creates symlinks in $HOME for all files in the group
• unlink removes symlinks from $HOME for all files in the group
• Group operations work on files already managed by Tildr

tildr profile

Manages profile variants for machine-specific dotfiles. This is the main workflow for keeping one dotfiles repository while switching between machines, distributions, jobs, or personal setups.

Files in common/ are shared everywhere and are addressed as no-profile in profile commands. A named profile such as linux, work, or laptop can override any no-profile file. When you run tildr profile set <name>, Tildr stores that profile as active and immediately relinks $HOME so matching files point to profiles/<name>/, while everything else keeps pointing to common/.

tildr profile create work --description "Work environment"
tildr profile add no-profile --files .bashrc .ssh/config --to work
tildr profile mv no-profile --to work                               # move all no-profile files to work
tildr profile mv no-profile -f .bashrc --to work                    # move .bashrc to work
tildr profile mv no-profile -f ~/.xinitrc --to work                 # HOME paths are accepted
tildr profile mv work --to no-profile                               # restore all from work to no-profile
tildr profile add work -f .bashrc --to personal                     # copy .bashrc between profiles
tildr profile rename                                                # interactive rename
tildr profile rename linux archlinux --description "Dotfiles Arch Linux"
tildr profile del work
tildr profile list
tildr profile list --long
tildr profile list work --long
tildr profile list --less
tildr profile set work                                          # activates and relinks $HOME
tildr profile current
tildr profile unset                                             # returns links to no-profile files
tildr profile migrate
tildr profile migrate --dry-run

Options:

List options:

File arguments for profile add -f and profile mv -f are logical HOME paths. You can use .bashrc, ~/.bashrc, $HOME/.bashrc, absolute paths inside $HOME, paths relative to your current directory when you are inside $HOME, or compatibility storage paths such as common/.bashrc and profiles/linux/.bashrc.

profile rename can run fully interactively:

Enter current profile name:
Enter new profile name:
Enter description:

When --description is omitted in CLI mode, the existing description is preserved. In interactive mode, pressing Enter at the description prompt also preserves the existing description.

Active Profile

The active profile is a per-file override mechanism. When tildr apply, tildr status, or tildr doctor processes a managed file, the resolution works as follows:

1. Check if the file has a variant in the active profile
2. If yes, use the profile variant (profiles/<name>/<file>)
3. If no, fall back to the no-profile version (common/<file>)
4. If no shared no-profile version exists, fall back to legacy profiles/common/<file>
5. If no legacy shared version exists, fall back to legacy profiles/default/<file> or root files

Files that exist only in an inactive named profile are not linked until that profile is activated. For every effective logical path, the active profile determines which physical variant is used.

Example: if the active profile is work and it tracks .bashrc and .ssh/config:

• ~/.bashrc → profiles/work/.bashrc (profile variant)
• ~/.ssh/config → profiles/work/.ssh/config (profile variant)
• ~/.gitconfig → common/.gitconfig (no-profile version, not in profile)

Switching profiles applies the new links right away:

tildr profile set work
# ~/.bashrc now points to profiles/work/.bashrc when that variant exists

tildr profile set personal
# ~/.bashrc now points to profiles/personal/.bashrc when that variant exists

tildr profile unset
# ~/.bashrc falls back to the no-profile source at common/.bashrc

Migration

Use tildr profile migrate when you have an older repository with dotfiles at the repository root or in legacy profiles/common/ and want to adopt the profile layout. It moves shared dotfiles and directories into common/, preserving their relative paths. It does not move Tildr internals or repository control files such as .tildr/, .git/, .github/, .gitignore, .tildrignore, or named profiles under profiles/.

Preview the migration first:

tildr profile migrate --dry-run

Example dry-run output:

  Would migrate: .bashrc -> common/.bashrc
  Would migrate: .gitconfig -> common/.gitconfig
  Would migrate: .config -> common/.config
  Would migrate: profiles/common/.zshrc -> common/.zshrc

Would migrate: 4 file(s) would be moved to common/ (dry run)

Then perform the migration:

tildr profile migrate
tildr profile list --long
tildr status

Before:

~/.dotfiles/
  .bashrc
  .gitconfig
  .config/nvim/init.lua
  .tildr/

After:

~/.dotfiles/
  .tildr/
  common/
    .bashrc
    .gitconfig
    .config/nvim/init.lua
  profiles/

Behavior:

• Profiles are stored in .tildr/profiles.json in the repository root
• no-profile is the command argument for shared files stored in common/; common remains accepted for compatibility
• Legacy repositories with profiles/common/ are still supported as a fallback
• default is only kept as a legacy compatibility fallback
• add copies files preserving the source; mv moves files atomically when possible
• Existing destination variants are skipped instead of overwritten
• mv removes empty source directories left after moving files
• Without -f, add/mv operate on all eligible files (orphans for no-profile, all tracked files for a profile)
• del removes the profile directory and restores orphaned files to common/
• rename supports empty profiles, renames the profile directory, updates the active profile name, and immediately repairs affected links
• set and unset immediately relink $HOME to the new effective profile
• del relinks $HOME after deletion, so removed active profiles fall back to no-profile files
• apply can be run manually to repair or reapply links using the active profile
• status uses the active profile to verify symlink targets match the expected variant
• doctor uses the active profile to check symlink integrity
• Files not in the active profile fall back to the no-profile version
• Only one profile can be active at a time
• Auto-commits changes to the repository

Example structure:

common/
  .bashrc                            # no-profile version
  .ssh/config                        # no-profile SSH config
profiles/
  work/
    .bashrc                          # work variant
    .ssh/config                      # work SSH config
  personal/
    .bashrc                          # personal variant

tildr info

Displays project metadata.

tildr info credits
tildr info license

Modes: