Skip to content

ADR 006: Unified Command Interface

Date: 2026-01-31 Status: Accepted Author: Jeremy Dawson

Context

The dotfiles repository had accumulated multiple fragmented command interfaces over time: - Core dotfiles operations scattered across mise run tasks and standalone commands - Chezmoi operations accessed via 7 separate aliases (cz, cza, czd, cze, czu, czs, czr) - Deprecated backward-compatibility aliases (dot-*) adding namespace pollution - Standalone utility commands (dotlog, dothelp) duplicating functionality - Shell customization via standalone functions (welcome-toggle, welcome-status) - GitHub gist management via unified gist command (already well-designed)

This fragmentation led to: - Discoverability issues: Users had to remember many different command names - Inconsistent patterns: Some operations used mise run, others used aliases - Namespace pollution: 21+ top-level commands for dotfiles operations - Documentation complexity: Multiple help systems (dots help, dothelp, individual READMEs) - Maintenance burden: Changes required updates across many locations

Decision

Consolidate all dotfiles operations under a single unified dots command with logical subcommands:

Command Structure

dots <command> [subcommand] [options]

Categories: - Core Operations: install, update, sync, doctor, backup - Chezmoi Management: cz apply|diff|edit|status|reinit - Utilities: log (changelog) - Shell Customization: welcome show|toggle|status - Help: help (unified documentation)

Key Principles

  1. Single Entry Point: All dotfiles operations accessible via dots
  2. Logical Grouping: Related operations grouped under subcommands
  3. Short Aliases: Power users get abbreviations (dots cz a, dots w t)
  4. Self-Documenting: dots help shows all commands with descriptions
  5. Passthrough Support: dots cz <any-cmd> for advanced chezmoi usage
  6. Clean Migration: Remove all deprecated/redundant commands in one go

Implementation Details

Removed (19 commands): - 7 chezmoi aliases: cz, cza, czd, cze, czu, czs, czr - 10 deprecated aliases: dot-install, dot-update, dot-sync, dot-doctor, dot-check, dot-uninstall, dot-backup, dot-prune, dot-ssh, dot-shell - 1 utility alias: dotlog - 1 duplicate function: dothelp

Added (1 unified interface): - dots command with subcommand routing and help system

Preserved: - gist command (already well-designed, separate concern) - dot alias (3 chars, too convenient to change)

Welcome Message Behavior Change

Changed welcome message from opt-out to opt-in: - Before: Enabled by default, disable via ~/.cache/welcome/.disabled - After: Disabled by default, enable via ~/.cache/welcome/.enabled - Rationale: Faster shell startup by default, explicit enablement

Consequences

Positive

  1. Improved Discoverability: dots help shows everything in one place
  2. Consistent Interface: All dotfiles operations follow same pattern
  3. Reduced Namespace: 21 → 2 top-level commands (dots, gist)
  4. Better UX: Logical grouping, short aliases, intuitive naming
  5. Easier Maintenance: Single source of truth for command routing
  6. Faster Defaults: Shell startup <100ms with welcome disabled by default

Negative

  1. Breaking Change: Users must migrate from old commands
  2. Learning Curve: Existing users need to learn new commands
  3. More Keystrokes: Some operations now require more typing (mitigated by short aliases)

Migration Path

Created comprehensive migration guide in documentation: 

# Old → New
cza               → dots cz apply    (or: dots cz a)
czd               → dots cz diff     (or: dots cz d)
dotlog            → dots log
dot-install       → dots install
welcome-toggle    → dots welcome toggle

Alternatives Considered

  1. Keep fragmented commands: Rejected due to discoverability and maintenance issues
  2. Gradual migration with deprecation warnings: Rejected to avoid prolonged dual-state complexity
  3. Unify under mise instead of dots: Rejected because mise is for task running, dots is for dotfiles operations
  4. Make more aggressive consolidations (theme, bitwarden): Rejected because those serve different concerns

Validation

  • ✅ All 41 tests passing
  • ✅ Integration tests verify workflows
  • ✅ Documentation updated across all files
  • ✅ No lingering references to old commands
  • ✅ Shellcheck clean for new code
  • ✅ Zero AI attribution in codebase

References

  • Implementation: dot_aliases lines 267-580
  • Tests: tests/aliases.bats, tests/welcome.bats
  • Documentation: CLAUDE.md, CHEATSHEET.md, TOOLS.md
  • Roadmap: docs/ROADMAP.md v1.4.0