CLI Reference

Installation

brew tap dotkit-run/cli
brew install dotkit

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

dotkit apply

Apply a profile directory. Processes folders in execution order.

dotkit apply [--dry-run] DIR

Flag	Description
`--dry-run`	Print what would run without executing

Execution order: configs/ → tools/ → packages/ → other run folders → link folders → todo folders.

Customize with order.txt in DIR. Prefix with ! to exclude a folder.

Examples:

dotkit apply profiles/personal
dotkit apply --dry-run profiles/work

dotkit run

Execute a dotkit file, shell script, URL, or remote module.

dotkit run [--extension EXT] FILE|URL|REMOTE

Argument	Description
`FILE`	Local file. No extension probes `.sh` → `.txt` → `.md`
`URL`	Remote URL. Extension required.
`REMOTE`	GitHub ref. See formats below.

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

Examples:

dotkit run packages/brew
dotkit run :tools/brew
dotkit run dotkit-run/[email protected]:tools/node-fnm
dotkit run https://raw.githubusercontent.com/dotkit-run/community/HEAD/tools/rust.txt

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 active profile 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.

Requires an active profile (set by the bootstrap installer or DOTKIT_PROFILE_DIR env var).

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 SRC [DEST]

If DEST is omitted, reads DEST from SRC/link.env.

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.

link.env, todo.env, and run.env are never symlinked.

Examples:

dotkit link dotfiles
dotkit link profiles/personal/dotfiles ~

dotkit todo

Generate a TODO.md checklist from a structured directory.

dotkit todo [-f] DIR

Flag	Description
`-f`, `--force`	Overwrite existing `TODO.md`

Reads todo.env for output location and heading. index.txt / index.md contributes content at the top level; other files and subdirectories become subsections.

Examples:

dotkit todo profiles/personal/manual
dotkit todo -f profiles/personal/manual

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.

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

Manage the dotkit CLI installation.

dotkit self update
dotkit self uninstall

If dotkit was installed via Homebrew, use brew upgrade dotkit instead.