Dotfiles management, but user-friendly.

CLI tool to manage files and directories via symlinks, backed by your own Git repository.

Features

• init: configure a remote Git repository and create local storage/config.
• link: move files/directories into storage and place a symlink at the original path.
• unlink: restore files/directories to their original path and remove the symlink.
• status: show current state (including Git status).
• push: commit and push pending changes to the remote repository.
• doctor: verify setup health (config, paths, Git remote).
• reset: restore all tracked files and remove dotfiles storage and config entirely.
• ui or status --web: start a local, read-only control panel in the browser.

Requirements

• Node.js 20+
• macOS or Linux

Installation

Global install via npm

npm install -g dotfiles

One-off run via npx

npx dotfiles --help

For local development in this repository:

npm install
npm run build

Then run locally with:

npx . --help

Initial setup

Provide your own Git remote during setup:

dotfiles init --remote git@github.com:username/dotfiles-backup.git

Optional paths:

dotfiles init --remote <git-url> --storage <path> --config <path>

Defaults:

• Config: platform-specific via env-paths (for example Linux ~/.config/dotfiles/config.json)
• Storage: platform-specific via env-paths (for example Linux ~/.local/share/dotfiles)
• Repository: <storage>/repo

When using a custom --config path, init prints an export hint so you do not have to pass --config on every subsequent command:

To avoid passing --config on every command, add to your shell config:
  export DOTFILES_CONFIG=/path/to/config.json

All commands respect the DOTFILES_CONFIG environment variable as a fallback between --config and the default path.

Usage

Link files or directories

dotfiles link ~/.zshrc ~/.gitconfig

Per path this will:

1. Move the item to <repo>/<absolute-path-without-leading-slash>.
2. Create a symlink at the original location to that new location.
3. Register the item in .dotlinks.json inside the repository.

Unlink files or directories

dotfiles unlink ~/.zshrc

Per path this will:

1. Verify the original location is a symlink.
2. Verify the symlink target is inside the storage repository.
3. Move the item back to the original location.
4. Remove the entry from .dotlinks.json.

View status

dotfiles status
dotfiles status --json

Push changes to remote

dotfiles push
dotfiles push --message "add work config"

Stages all changes in the repository, commits, and pushes to the configured remote. If the repository is already clean, it exits without doing anything.

Check setup health

dotfiles doctor

Verifies:

• Config source (flag, $DOTFILES_CONFIG, or default)
• Config file exists and is valid
• Storage root directory exists
• Repo directory exists
• Repo is a valid Git repository
• Git remote matches the configured value

For symlink health, use dotfiles status.

Remove dotfiles entirely

dotfiles reset

Without --yes, prints a preview of what would happen and exits. To proceed:

dotfiles reset --yes

This will:

1. Restore all tracked files to their original paths.
2. Remove the storage root (including the Git repository).
3. Remove the config file.

If any file cannot be restored, the operation aborts before removing storage or config.

Open control panel

dotfiles ui
# or
dotfiles status --web

The server starts on port 4321 by default, with fallback to the next available port.

Commands

• dotfiles init --remote <git-url> [--storage <path>] [--config <path>]
• dotfiles link <paths...> [--config <path>]
• dotfiles unlink <paths...> [--config <path>]
• dotfiles status [--json] [--web] [--config <path>]
• dotfiles push [--message <msg>] [--config <path>]
• dotfiles doctor [--config <path>]
• dotfiles reset [--yes] [--config <path>]
• dotfiles ui [--config <path>]
• dotfiles version

Exit codes

• 0: success
• 1: user error (for example invalid path or conflict)
• 2: operational error (for example Git/IO/permission failure)

Conflict policy

This version is strict:

• If the storage destination already exists during link, the operation fails.
• If a path does not match unlink expectations (not a symlink, target outside repo, missing target), the operation fails.

No automatic overwrite or backup rename is performed.

Development

npm install
npm run typecheck
npm run test
npm run build

Important directories:

• src/commands: CLI commands
• src/core: core logic (config, link/unlink, status, git)
• src/web: local control panel
• test: unit tests