cli-reference.md

CLI Reference

Complete reference for all dots commands, flags, and subcommands.

Global Flags

These flags are available on every command:

Flag	Short	Default	Description
--config	-c	(auto-detect)	Path to config file
--log-file		stderr	Write logs to file
--log-level		info	Minimum log level
--log-json		false	Output logs as JSON
--version			Show version

Initialization

dots init

Initialize the dots environment. Creates a default config file if one doesn't exist.

dots init
dots init --from git@github.com:you/dotfiles.git --path dots
dots init --from git@github.com:you/dot-personal.git --name private --path dots-config

Flag	Description
--from	Git URL to clone as initial tap
--path	Package path within the tap to install
--name	Tap name for the --from clone (default: default). Set this to match the tap name declared in the bootstrap package's config.yaml so the on-disk tap and the installed config agree.

When --from is specified, dots clones the repo as a tap and installs the package at --path from it.

If the bootstrap package (the one at --path) ships a config.yaml that declares the same repo as a named tap (e.g. taps.private.url matching --from), pass --name private so dots registers the clone under private rather than the generic default. Otherwise dots ends up with two taps — default and private — pointing at the same URL.

Cleaning up a duplicate tap

If a prior dots init --from <URL> --path <pkg> left a stale default tap next to the name declared in the installed config, remove the orphan:

dots tap remove default

Tap Management

dots tap add

Register a new tap (package source).

dots tap add personal git@github.com:you/dotfiles.git
dots tap add work git@github.com:company/dotfiles.git --branch develop

Flag	Default	Description
--branch	main	Git branch to track

dots tap remove

Remove a registered tap. Aliases: rm.

Any packages installed from the tap are uninstalled first (links and lockfile entries removed). If the on-disk tap directory is already gone, lockfile entries are still cleaned up — use this to reconcile a tap whose state has drifted.

dots tap remove personal

dots tap list

List all registered taps. Aliases: ls.

dots tap list

Output: NAME\tURL per line.

dots tap update

Update tap(s) to latest from remote.

dots tap update              # update all taps
dots tap update personal     # update a specific tap

Package Operations

dots install

Install a dotfile package.

dots install personal/nvim
dots install personal/nvim --dry-run
dots install personal/nvim --strategy copy

Flag	Description
--dry-run	Print what would happen without writing
--strategy	Override link strategy: symlink, copy, hardlink

dots remove

Remove an installed package. Aliases: rm, uninstall.

dots remove personal/nvim

dots upgrade

Upgrade installed packages.

dots upgrade personal/nvim   # upgrade one package
dots upgrade --all           # upgrade all installed packages

Flag	Description
--all	Upgrade all installed packages

dots reinstall

Remove then reinstall a package.

dots reinstall personal/nvim

dots sync

Sync copy-strategy packages with their source files.

dots sync personal/nvim      # sync one package
dots sync --all              # sync all copy-strategy packages

Flag	Description
--all	Sync all copy-strategy packages

Discovery

dots list

List packages. Aliases: ls.

dots list                    # list installed packages
dots list --available        # list available (uninstalled) packages
dots list --tap personal     # filter by tap

Flag	Description
--available	List available (not installed) packages
--tap	Filter by tap name

dots search

Search packages across all taps.

dots search nvim

Output marks installed packages with *.

dots browse

List all packages in a tap with details.

dots browse personal

Shows package name, version, description, tags, link count, and installation status.

dots info

Show package or platform information.

dots info personal/nvim      # package details
dots info --platform         # current platform

Flag	Description
--platform	Show platform info instead of package info

Inspection

dots status

Show dots status overview.

dots status

Output includes platform, config path, state directory, link strategy, active profile, tap count, and package count.

dots doctor

Run diagnostic checks on config, taps, and links.

dots doctor

Output: [OK|WARN|ERROR] CheckName: detail per check.

dots diff

Show differences between source and installed files.

dots diff personal/nvim

dots which

Identify which package placed a file.

dots which ~/.config/nvim/init.lua

Profiles

dots profile create

Create a new empty profile.

dots profile create work

dots profile delete

Delete a profile.

dots profile delete work

dots profile list

List all profiles. Aliases: ls.

dots profile list

dots profile show

Show profile details (name, extends, packages).

dots profile show work

dots profile add

Add packages to a profile.

dots profile add work personal/zsh personal/nvim personal/git

dots profile remove

Remove a package from a profile.

dots profile remove work personal/git

dots profile apply

Install all packages in a profile.

dots profile apply work

dots profile switch

Switch to a different profile (sets it as active).

dots profile switch personal

dots profile export

Export a profile as YAML to stdout.

dots profile export work > work-profile.yaml

dots profile import

Import a profile from a YAML file.

dots profile import work-profile.yaml

Work Mode

dots work on

Rewire links to a local checkout for development.

dots work on personal ~/code/dotfiles

dots work off

Rewire links back to the internal clone.

dots work off personal

dots work status

Show which taps are in work mode.

dots work status

dots work rebuild

Re-link packages after local changes.

dots work rebuild                    # rebuild all
dots work rebuild personal/nvim      # rebuild one package