.dotfiles Manual

Cookbook

Cookbook: Recipes

Thirty short recipes for common tasks.

Installation & Update

1. Install on a fresh machine

# After the verified release download in the installation guide:
bash /tmp/dotfiles-install.sh

2. Update everything

dot upgrade

3. Update dotfiles only (no tools)

dot update

4. Preview what would change

dot apply --dry-run

Themes

5. Switch to a specific theme

dot theme tahoe-dark

6. Toggle between dark and light

dot theme toggle

7. Open the interactive theme picker

dot theme

8. List paired wallpaper themes

dot theme list

9. Add a new wallpaper-driven theme

cp my-wallpaper.jpg ~/Pictures/Wallpapers/myname-dark.jpg
cp my-wallpaper-light.jpg ~/Pictures/Wallpapers/myname-light.jpg
bash scripts/theme/merge-wallpaper.sh myname
dot theme rebuild
dot theme myname-dark

10. Regenerate all themes from scratch

dot theme rebuild --force

Configuration

11. Edit the source directory

dot edit

12. Add a new config file to chezmoi

dot add ~/.some-config-file

13. Remove a managed file

dot remove ~/.some-config-file

14. Show configuration drift

dot status

15. Show diff against source

dot diff

Secrets

16. Encrypt a new secret file

chezmoi add --encrypt ~/some-secret.txt

17. Edit an encrypted file

sops dot_config/credentials.sops.yaml
# or
chezmoi edit ~/some-secret.txt.age

18. Rotate your Age key

age-keygen -o ~/.config/age/keys.txt.new
# Update .sops.yaml with new public key
# Then:
find . -name '*.sops.yaml' -exec sops updatekeys {} \;
git commit -sS -am "chore(secrets): rotate age key"

19. Check for accidental secret leaks

dot verify --security

Diagnostics

20. Quick health check

dot doctor

21. Auto-fix common issues

dot heal

22. Check startup performance

dot benchmark

23. See the health score

dot score

24. Recent metrics

dot metrics

Fleet

25. Attest across all fleet hosts

dot fleet attest

26. Sync dotfiles to every fleet host

dot fleet sync

27. Diff config across hosts

dot fleet diff

AI & Agents

28. Show installed AI tools

dot ai

29. Switch agent profile

dot mode architect   # or hardener, refactor

30. Verify MCP policy

dot mcp --strict

Recovery

31. Rollback the last apply

dot rollback

32. Create an offline bundle

dot bundle

33. Restore from a bundle

dot bundle restore ~/Downloads/dotfiles-bundle-*.tar.zst

Development

34. Run a test locally

bash tests/unit/theme/test_themes_toml.sh

35. Run all tests

./tests/framework/test_runner.sh

36. Lint shell scripts

dot lint

37. Simulate chaos to test self-healing

dot chaos symlink   # in an ephemeral container only
dot heal
dot doctor

Manual

38. Open the manual in a browser

dot manual

39. Download the PDF

dot manual pdf

40. Read the manual in a terminal

dot manual text | less

See Also