CLI Reference

Installation

brew tap dotkit-run/cli
brew install dotkit

Or via the bootstrap installer. Dotkit CLI is installed automatically.

dotkit run

Execute a file, a directory, or a remote dotkit file. One command for everything executable.

dotkit run [--dry-run] [--extension EXT] PATH|URL|REMOTE
dotkit run --list DIR

Flag	Description
--dry-run	Print what would run without executing
--list	List the dotkit files in a directory
--extension EXT	Force a format when it cannot be inferred

Resolution:

Argument	Behaviour
file	Execute it
directory with a default	Execute that target, no prompt
directory with other kits	Ask which target, or the folder’s own files
directory with no kit	Execute its .txt/.md/.sh, alphabetically
URL or remote ref	Fetch, then execute

Default targets, highest precedence first. Any lower one that exists is reported as ignored:

default.dotkit   index.dotkit   <foldername>.dotkit   .dotkit

A default is the only thing that suppresses the prompt. With no terminal attached the prompt becomes an error listing candidates, so unattended runs never stop to ask. See Kits.

Paths. An extensionless argument probes .txt, .md, .sh, .dotkit in that order. If both a directory and a file match, run refuses rather than guessing; add a trailing slash to mean the directory.

Remote formats:

Format	Resolves to
:path	dotkit-run/community at path
org/repo:path	Any GitHub repo at path
org/repo@ref:path	Pinned to tag, branch, or SHA

Local files pick up the kit environment and run from their own directory. Fetched files have neither.

Examples:

dotkit run .
dotkit run ./configs
dotkit run ~/dotkit/mac.dotkit
dotkit run packages/brew
dotkit run --list .
dotkit run --dry-run ~/dotkit
dotkit run :tools/brew
dotkit run dotkit-run/[email protected]:tools/node-fnm

dotkit add

Append items to a map block in a module file and run them immediately.

dotkit add [FLAGS] MODULE [ITEMS...]

MODULE is relative to the kit directory. File lookup order: .txt → .md → .sh.

Flag	Description
(none)	Interactive: show map blocks, pick one, enter items, confirm
-y	Skip confirmation. Auto-pick if only one map block.
-y0	Use last map block. Skip confirmation.
-y1..-y9	Use Nth map block (1 = first). Skip confirmation.

Which kit. The kit is wherever you are standing. dotkit add walks up from the current directory to the nearest kit root, stopping at your home directory and at /.

The nearest kit wins and is final. A missing module inside it is an error, not a reason to look in another kit, so standing in a project repo will never quietly edit your personal dotfiles:

$ dotkit add packages/brew ripgrep
dotkit add: no packages/brew in this kit (/Users/you/dev/someapp)
cd into the kit that has it.

Outside any kit this is an error. cd to the kit you mean.

Examples:

dotkit add packages/brew neovim
dotkit add -y packages/brew ripgrep fd bat
dotkit add -y1 packages/brew neovim

dotkit link

Symlink files from SRC into DEST, mirroring the directory structure.

dotkit link [--dry-run] SRC [DEST]

DEST defaults to ~, which is where dotfiles go in almost every case. Pass it explicitly for anything else; it may be absolute, ~/path, or relative to SRC.

Flag	Description
--dry-run	Print what would be linked and backed up

Destination state	Action
Missing	Symlink created
Correct symlink	Reported ok, skipped
Stale symlink	Backed up, replaced
Real file	Backed up (with diff), replaced

Backups use the pattern filename.bak.YYYYMMDDHHMMSS.

*.env and *.dotkit files are never symlinked.

Examples:

dotkit link dotfiles
dotkit link dotfiles ~
dotkit link --dry-run dotfiles
dotkit link etc /etc

dotkit todo

Generate a TODO.md checklist from a structured directory.

dotkit todo [-f] [--dry-run] [--title TITLE] [--out PATH] DIR

Flag	Description
-f, --force	Overwrite existing output
--dry-run	Print the output path and generated markdown
--title TITLE	H1 heading. Default: the directory name.
--out PATH	Output directory or full .md path. Default: DIR/TODO.md

index.txt / index.md contributes content at the top level; other files and subdirectories become subsections.

Examples:

dotkit todo todo
dotkit todo -f --out ~/TODO.md todo
dotkit todo --title 'Manual Steps' --dry-run todo

dotkit map

Apply a template to each row of data from stdin.

dotkit map TEMPLATE <<BODY
row1
key = value
BODY

Rows split on =. Blank lines and # comments skipped.

Placeholder	Alias	Value
{{1}}	{{item}}, {{key}}	First field
{{2}}	{{value}}	Second field
{{3}}	N/A	Third field

Examples:

dotkit map 'brew install {{item}}' <<BODY
gh
ripgrep
BODY

dotkit map 'git config --global {{key}} {{value}}' <<BODY
user.name = Your Name
user.email = [email protected]
BODY

dotkit parse

Parse a dotkit file and emit shell to stdout without executing.

dotkit parse [--extension EXT] FILE

Useful for debugging or piping into a custom executor. dotkit run --dry-run prints the same thing along with the resolved path.

Examples:

dotkit parse packages/brew.txt
dotkit parse packages/brew.md | sh
dotkit parse --extension txt packages/brew

dotkit install

Download and execute an installer script.

dotkit install URL [-- ARGS...]

Downloads with curl (or wget as fallback). Pass -- ARGS to forward arguments to the installer.

Examples:

dotkit install https://sh.rustup.rs -- -y
NONINTERACTIVE=1 dotkit install https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh

dotkit self

Operate on the dotkit CLI itself, not on your kits.

dotkit self about
dotkit self update
dotkit self dismiss
dotkit self uninstall

$ dotkit self about
current  0.2.0
install  ~/.local/bin
manager  dotkit
upgrade  dotkit self update

latest   0.2.0
github   https://github.com/dotkit-run/cli
dotkit   https://www.dotkit.run

Who owns updating. self update and self uninstall only work when dotkit installed itself into ~/.local/bin. If a package manager put it there, both refuse and name the command that does work:

$ dotkit self update
dotkit self update: dotkit was installed to /opt/homebrew/Cellar/dotkit/0.2.0/libexec,
which dotkit does not manage.

  brew upgrade dotkit

Overwriting files a package manager owns leaves its records disagreeing with disk, so this is a refusal rather than a warning. Packagers set the suggested command by patching DOTKIT_UPDATE_COMMAND at build time.

Update checks run at most once every 7 days, only for self-managed installs, only on a terminal, and announce themselves rather than running in the background. A failed check still records the timestamp, so an offline machine is bothered once a week instead of once a command.

Migration notices appear after a breaking upgrade and repeat on every invocation until dotkit self dismiss. Pre-1.0 every minor release counts as breaking; from 1.0 on, only majors. These show for package-managed installs too, since the state file outlives whatever replaced the binary.

dotkit version

Print the installed version.

dotkit --version
dotkit -v

dotkit 0.2.0

Neither triggers an update check, so both are safe in a script. For the fuller picture use dotkit self about.