Skip to content

CLI Reference

The dots command is the unified entry point for managing this repository. It wraps mise tasks and other utilities to provide a consistent interface for managing your dotfiles, tools, and system configuration.

Usage

dots <command> [args]

Dashboard

Running dots with no arguments shows a fast status dashboard (~200ms) with a glanceable overview of your environment:

dots — dotfiles dashboard

  repo     main ✓
  chezmoi  clean
  tools    52 installed (mise)
  health   ok (2h ago)

  Run 'dots help' for all commands

When issues are detected, actionable next steps are suggested automatically. The dashboard is also available as dots status, dots st, or dots s.

Use dots help for the full command reference.

Core Commands

Command Alias Description Mapped Task
dots bootstrap boot Run repository bootstrap (installs prerequisites, then install flow). scripts/bootstrap
dots install i Install dotfiles and tools. mise run install
dots update up Update dotfiles, tools, and system packages. mise run update
dots doctor dr Check system health and configuration. mise run doctor
dots test t Run the validation suite (BATS). mise run test
dots chezmoi cz Wrapper for chezmoi commands. chezmoi

dots check is a compatibility alias for dots doctor.

Maintenance Tasks

  • dots backup: Create a backup of current configuration.
    • Usage: dots backup
  • dots prune: Clean up unused tools and cache to free space.
    • Usage: dots prune
  • dots check-outdated: Check for outdated tool versions.
    • Usage: dots check-outdated

Security Operations

  • dots setup-secrets: Initialize age encryption for secrets.
    • Usage: dots setup-secrets
  • dots rotate-secrets: Rotate the age encryption key.
    • Usage: dots rotate-secrets
  • dots setup-ssh: Generate SSH keys and configure agent.
    • Usage: dots setup-ssh

Development & Testing

  • dots shell: Start an interactive devcontainer environment.
    • Usage: dots shell
  • dots lint: Run all linters (shellcheck, yamllint, etc.).
    • Usage: dots lint
  • dots profile: Analyze shell startup performance.
    • Usage: dots profile
  • dots perf: Quick benchmark of shell startup.
    • Usage: dots perf

Documentation

  • dots docs-serve: Preview documentation locally.
    • Usage: dots docs-serve
  • dots docs-build: Build the static documentation site.
    • Usage: dots docs-build
  • dots validate-links: Check for broken links in docs.
    • Usage: dots validate-links

Release Management

  • dots changelog / dots log: View the changelog file.
    • Usage: dots changelog
  • dots release: Create a new release with automated changelog.
    • Usage: dots release

Sync & Version Control

  • dots sync: Sync dotfiles repo (git pull + push).
    • Usage: dots sync

Pre-commit & Code Quality

  • dots pre-commit / dots pc: Run pre-commit hooks.
    • Usage: dots pre-commit
  • dots test-coverage / dots cov: Generate test coverage report.
    • Usage: dots test-coverage

Shell Customization

  • dots welcome / dots w: Manage the welcome message (weather + quotes).
    • Usage: dots welcome (show), dots welcome toggle (enable/disable), dots welcome status

Uninstall

  • dots uninstall: Remove dotfiles and undo symlinks.
    • Usage: dots uninstall

Examples

Update everything and check health: 

dots up && dots dr

Run specific tests: 

dots t tests/dots_task_preflight.bats

Manage dotfiles directly: 

dots cz add ~/.zshrc
dots cz git commit -m "update zshrc"