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

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/nvim/init.lua --dry-run
tildr add .bashrc .config/nvim/init.lua
tildr add .config/app01.json --nolink

Options:

Behavior:

• 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
• 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 --dry-run
tildr apply --force --verbose

Options:

Behavior:

• Creates missing symlinks for all managed files
• Repairs broken or incorrect symlinks automatically
• Skips regular files already present in $HOME unless --force is used
• Uses the repository as the source of truth
• Does not modify repository content

tildr status

Shows the synchronization state of all managed files.

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

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 in the repository.

tildr list
tildr list --long
tildr list --tree

Options:

Notes:

• Standard listing includes only managed files discovered by repository scanning
• Tree view prints the repository directory structure directly
• .tildrignore patterns and internally excluded files are not shown

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 .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
• 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

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 over managed files
• 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
• 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
• 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, or fish.

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 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
• 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 remove *.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 info

Displays project metadata.

tildr info credits
tildr info license

Modes: