Getting Started

Prerequisites

@dotformat/cli requires the Bun runtime (>= 1.0). Install it:

curl -fsSL https://bun.sh/install | bash

Verify:

bun --version

Why Bun?

The CLI uses Bun.file(), Bun.$, Bun.Glob, Bun.hash, and Bun.color throughout. It won't run on Node.js. The entry point (bin/dotfiles.ts) checks for Bun at startup and exits with a clear error if it's missing.

Installation

Option A: Run directly (no clone)

bunx @dotformat/cli collect
bunx @dotformat/cli backup
bunx @dotformat/cli scan ~/.ssh/config

This downloads the package on first run and caches it. Good for quick one-off snapshots.

Option B: Clone the repository

git clone https://github.com/doguyilmaz/dotfiles.git
cd dotfiles
bun install

Then run commands via:

bun bin/dotfiles.ts collect
bun bin/dotfiles.ts backup

Or use the npm script shortcuts:

bun run collect
bun run backup
bun run scan
bun run restore
bun run diff
bun run compare

Option C: Global install

bun install -g @dotformat/cli
dotfiles collect

Output Directory

Where reports and backups land depends on context:

Condition	Output Directory
-o /path provided	That exact path
Running inside a git repo (.git/HEAD exists in cwd)	<cwd>/reports/
Running outside a git repo (global/standalone)	~/Downloads

You can always override with the -o flag:

dotfiles collect -o ~/my-reports
dotfiles backup -o /tmp/backup-test

Core Journeys

Journey A: "What's on my machine?"

Generate a .dotf snapshot — a single parseable text file capturing your entire machine config.

dotfiles collect                           # Full snapshot
dotfiles collect --slim                    # AI-friendly (truncated content)
dotfiles list brew                         # Query a section from latest report
dotfiles compare home.dotf work.dotf       # Diff two snapshots

The .dotf format is structured text with sections, key-value pairs, and content blocks. It's designed to be human-readable, git-diffable, and parseable by @dotformat/core.

Journey B: "Back up my configs"

Copy real files into a structured directory. Two tracks:

Clone track (power users): backup writes into repo → git add . && git commit && git push to your private repo.

CLI-only track (quick & portable): use --archive for a .tar.gz you can email, AirDrop, or store anywhere.

dotfiles backup                            # Full structured backup
dotfiles backup --only ai,shell            # Just AI + shell configs
dotfiles backup --skip editor,npm          # Everything except editors and npm
dotfiles backup --archive                  # Export as .tar.gz
dotfiles backup --archive -o ~/Desktop     # Archive to specific location

Journey C: "Set up a new machine"

Restore from a backup with full safety features — interactive picker, dry run preview, conflict resolution, and automatic rollback snapshots.

dotfiles restore ./backup --dry-run        # Preview what would change
dotfiles restore ./backup --pick           # Select categories interactively
dotfiles restore ./backup                  # Restore everything

Journey D: "What changed?"

Compare your backup against the current machine state. Track drift.

dotfiles diff                              # Full diff (auto-finds latest backup)
dotfiles diff --section ai                 # Just AI configs
dotfiles status                            # Quick summary: modified count, age

Sensitivity — Safe by Default

Every collect and backup run automatically scans for sensitive data. The CLI:

1. Detects 27+ patterns (API keys, tokens, private keys, IPs, passwords, DB URLs)
2. Classifies each finding as HIGH / MEDIUM / LOW severity
3. Acts: redacts values, skips entire files, or includes with warnings

After every run, you see a sensitivity report:

⚠ Sensitivity report:
  HIGH   ~/.ssh/id_ed25519         private key — skipped
  HIGH   ~/.npmrc                  auth token — redacted
  MEDIUM ~/.gitconfig              email address — included

  2 items redacted, 1 skipped. Use --no-redact to include all.

To bypass redaction (e.g., for a private encrypted repo):

dotfiles collect --no-redact
dotfiles backup --no-redact

See Sensitivity and Redaction for the full pattern list and action rules.

Timestamped Output

All outputs use timestamped names to prevent overwrites:

Output Type	Naming Pattern
Collect report	<hostname>-YYYYMMDDHHMMSS.dotf
Backup directory	backup-<hostname>-YYYYMMDDHHMMSS/
Archive	backup-<hostname>-YYYYMMDDHHMMSS.tar.gz
Pre-restore snapshot	pre-restore-YYYYMMDDHHMMSS/

What's Next

• Commands — full reference for every command and flag
• Backup and Restore — safety features, conflict resolution, rollback
• Sensitivity and Redaction — all 27+ detection patterns
• Architecture — project structure, types, registry design
• Execution Flows — mermaid diagrams showing runtime behavior
• Behavior Reference — defaults, edge cases, caveats