Mise Tasks Reference¶

Complete guide to all available mise tasks in this dotfiles repository.

Quick Reference¶

Public Task Contract¶

The top-level tasks listed above are the stable public entrypoints (for example: install, update, doctor, test, setup-secrets).

• Public tasks are implemented as small wrappers in mise-tasks/.
• Wrappers delegate to internal namespaced implementations (for example maintain:*, dev:*, setup:*).
• --help on public wrappers is side-effect free and exits successfully.
• Internal namespaced task paths may evolve; scripts, docs, and automation should prefer the public names.

Installation Tasks¶

mise run setup¶

Interactive setup wizard for first-run configuration.

What it does: - Guides you through deployment mode selection (full/server/minimal) - Lets you choose which components to configure (shell, editor, git, ssh, secrets) - Saves preferences to ~/.config/dotfiles/setup.json - Optionally runs SSH key generation and secrets encryption setup

Usage:

mise run setup                  # Interactive wizard
mise run setup --non-interactive  # Use defaults (for automation)
mise run setup --reconfigure    # Re-run even if already configured

Flags: - --non-interactive - Skip all prompts, use defaults - --reconfigure - Re-run setup even if config exists

Deployment Modes: - full - All tools from mise.toml (workstations) - server - Server-safe tools from mise-server.toml - minimal - Dotfiles only, no tool installation

When to use: - First-time setup on a new machine - Changing deployment mode - Before running mise run install

mise run install¶

Install dotfiles and tools via chezmoi.

What it does: - Initializes chezmoi with the dotfiles repository - Applies dotfile templates to your home directory - Creates necessary symlinks - Installs mise-managed tools from mise.toml - Repairs invalid or partial TPM / Antidote checkouts before proceeding - In interactive workstation installs, prompts to install zsh if missing - If the account's system login shell is not zsh, prompts before attempting to switch it - Uses rollback-on-failure for plugin/config linking to avoid leaving partial state in $HOME

Usage:

mise run install

When to use: - First-time dotfiles installation - After cloning the repo to a new machine - After major configuration changes - Any time you want to converge a partially applied install back to the expected steady state

Shell behavior notes: - --server mode keeps default shell unchanged (bash baseline policy). - Non-interactive mode skips prompts; if zsh is missing, install continues with bash. - If the system login shell is already zsh, shell-change prompt is skipped. - Re-running mise run install keeps checking until the account shell is confirmed as zsh.

See also: Installation Guide

mise run uninstall¶

Remove dotfile symlinks and restore backups.

What it does: - Removes symlinks created by chezmoi - Restores original configuration files from backups - Cleans up mise-managed tools (optional)

Usage:

mise run uninstall

When to use: - Removing dotfiles from a system - Testing fresh installations - Troubleshooting broken symlinks

⚠️ Warning: This will remove all dotfile configurations. Ensure you have backups.

mise run update¶

Update dotfiles and tools to latest versions.

What it does: - Pulls latest changes from the dotfiles repository - Updates chezmoi-managed files - Refreshes mise-managed tools - Applies any new configurations

Usage:

mise run update
mise run update -- --auto-stash
mise run update -- --allow-dirty
mise run update -- --wait-for-lock
mise run update -- --fast
mise run update -- --offline
mise run update -- --dry-run
mise run update -- --skip-system-updates
mise run update -- --system-updates

Flags: - -y, --yes - Auto-confirm updates (non-interactive friendly) - --skip-system-updates - Skip privileged system package upgrades (currently gh) - --system-updates - Include privileged system package upgrades (may prompt for sudo) - --auto-stash - Temporarily stash local changes and restore them after update - --allow-dirty - Run update with local changes without stashing (advanced use) - --wait-for-lock - Wait for another dots update run to finish instead of failing fast - --fast - Core update only (skips plugin and system package update steps) - --full - Explicitly include optional update steps (still respects other skip flags) - --offline - Skip networked steps (git pull, plugin syncs, system package upgrades) - --dry-run, --plan - Print the resolved update plan and skip all mutations - --skip-verify - Skip the post-update smoke verification step

Default behavior for system package upgrades: - mise run update skips privileged package upgrades if sudo would prompt (non-interactive safety) - Use mise run update -- --system-updates when you want the package manager step included - Use mise run update -- --skip-system-updates to explicitly skip package manager upgrades - If gh is already mise-managed, the system package upgrade step is skipped automatically

When to use: - Weekly maintenance routine - After seeing update notifications - Before working on the dotfiles repo

Mode and safety notes: - Dirty repos are blocked by default; use --auto-stash (recommended) or --allow-dirty to override intentionally - --offline skips all networked update steps and conflicts with --system-updates - --fast skips plugin updates and system package updates but still runs core sync/apply/install - --dry-run may perform non-mutating checks (for example, sudo -n eligibility) to show accurate skip reasons

Auto-sync: If autoCommit is enabled in chezmoi config, changes are automatically committed and pushed.

Health Check Tasks¶

mise run doctor¶

Comprehensive environment health check.

What it checks: - Chezmoi configuration and age encryption - Critical configuration files (zshrc, gitconfig, etc.) - Directory structure and permissions - Git identity (user.name, user.email) - Environment variables - Tool versions - Git hooks (pre-commit, pre-push)

Usage:

mise run doctor              # Standard checks
mise run doctor --full       # Full checks including optional items
mise run doctor -- --fix     # Apply safe local repairs, then run checks

Flags: - -f, --full - Run all checks including optional ones - --fix - Apply safe, non-destructive local repairs (no sudo, no network) before checks

Environment variables: - SERVER_MODE=1 - Skip UI/desktop tool checks (for servers)

--fix currently repairs: - Missing execute bits on shell-based mise-tasks scripts - Missing or incorrect CLAUDE.md / GEMINI.md symlinks to AGENTS.md - Missing safe local directories (for example ~/.local/bin, ~/.config/mise, ~/.config/git/hooks)

Output: - ✓ Green checks - All good - ⚠ Yellow warnings - Non-critical issues - ✗ Red errors - Critical problems

Example:

$ mise run doctor
✓ Config: ~/.config/chezmoi/chezmoi.toml
✓ Age encryption key present
⚠ Reminder: Back up key.txt to password manager!
✓ Running in WSL
...
⚠️ 1 warning(s), but no critical errors.

When to use: - After installation or updates - Troubleshooting issues - Before making major changes - In CI/CD pipelines (with SERVER_MODE=1)

mise run test¶

Run the full BATS test suite.

What it tests: - Static checks (syntax, linting) - Smoke tests (basic functionality) - Environment configuration - Alias functionality - Tool integrations - Platform-specific features

Usage:

mise run test              # Run all tests
bats tests/smoke.bats      # Run specific test file

Test categories: - tests/static.bats - Static analysis - tests/smoke.bats - Basic functionality - tests/basic.bats - Core features - tests/env.bats - Environment setup - tests/aliases.bats - Shell aliases - tests/mise_tasks.bats - Task validation

Coverage: ~450+ tests across 43 files

CI vs Local: CI runs only fast tests (static, smoke, basic, env, doctor). Local runs the full suite.

See also: TESTING.md for test strategy

mise run test-coverage¶

Run tests with code coverage analysis.

Requirements: - kcov must be installed

Usage:

mise run test-coverage

Output: - Coverage report in coverage/ directory - HTML report for detailed analysis

When to use: - Improving test coverage - Identifying untested code paths - Before major refactoring

mise run lint¶

Run all linters on the codebase.

What it checks: - ShellCheck - Shell script linting - Zsh syntax - Zsh configuration validation - yamllint - YAML file linting - Taplo - TOML formatting

Usage:

mise run lint

Output:

🔍 Running linters...
🔍 Running ShellCheck...
🔍 Running Zsh syntax check...
🔍 Running YAML Lint...
🔍 Running TOML Lint (Taplo)...
✅ All checks passed!

Auto-fix: - Taplo can auto-format TOML: taplo fmt mise.toml

When to use: - Before committing changes - In pre-commit hooks - In CI pipelines

mise run pre-commit¶

Run pre-commit hooks on all files.

What it does: - Runs all configured pre-commit hooks - Includes: shellcheck, gitleaks, formatters - Fast checks only (skips slow tests)

Usage:

mise run pre-commit               # All files
pre-commit run --files file.sh    # Specific file

When to use: - Before committing - After modifying shell scripts - Manual validation

See also: .pre-commit-config.yaml for hook configuration

Development Tasks¶

mise run shell¶

Start an interactive development container.

What it does: - Launches a devcontainer environment - Installs all dependencies - Provides isolated testing environment

Usage:

mise run shell

Requirements: - Docker or Podman - VS Code (optional, for full integration)

When to use: - Testing dotfiles in clean environment - Development without affecting local system - Cross-platform testing

See also: .devcontainer/ directory

mise run profile¶

Profile zsh startup time and identify bottlenecks.

What it does: - Measures time for each zsh startup component - Identifies slow-loading plugins - Provides detailed timing breakdown

Usage:

mise run profile

Output:

Profiling zsh startup...
Plugin loading: 45ms
Aliases: 5ms
Tool initialization: 30ms
Total: 120ms

When to use: - Shell feels slow - After adding new plugins - Optimizing startup performance

Target: <150ms total startup time

mise run perf¶

Quick benchmark of shell startup time.

What it does: - Runs multiple shell startup iterations - Calculates average startup time - Simpler than profile, faster execution

Usage:

mise run perf

Difference from profile: - perf - Quick average timing - profile - Detailed component breakdown

Secrets Management Tasks¶

mise run setup-secrets¶

Initialize age encryption for secrets management.

What it does: 1. Generates age encryption key (if missing) 2. Configures chezmoi to use age 3. Encrypts ~/.secrets file 4. Creates encrypted_dot_secrets.age

Usage:

mise run setup-secrets

Interactive prompts: - Confirms before generating new key - Asks for backup confirmation

When to use: - First-time secrets setup - New machine configuration - Enabling encrypted secrets

See also: SECRETS.md for detailed guide

mise run rotate-secrets¶

Rotate age encryption key and re-encrypt all secrets.

What it does: 1. Generates new age key 2. Backs up old key 3. Re-encrypts all encrypted files with new key 4. Updates chezmoi configuration

Usage:

mise run rotate-secrets

When to use: - Key compromise suspected - Regular security rotation (annually) - Revoking access to old backups

⚠️ Warning: Old encrypted backups won't decrypt with new key.

See also: SECRETS.md - Key Rotation

Setup Tasks¶

mise run setup-ssh¶

Generate SSH keys and configure SSH agent.

What it does: - Generates ed25519 SSH key pair - Configures SSH agent for automatic key loading - Sets appropriate permissions - Optionally adds key to GitHub

Usage:

mise run setup-ssh

Generated files: - ~/.ssh/id_ed25519 - Private key - ~/.ssh/id_ed25519.pub - Public key

When to use: - New machine setup - Regenerating SSH keys - Automated server provisioning

Documentation Tasks¶

mise run docs-build¶

Build the static documentation site.

What it does: - Builds MkDocs site from docs/ directory - Validates internal links - Generates static HTML in site/

Usage:

mise run docs-build

Output: - Static site in site/ directory - Build logs showing warnings/errors

When to use: - Before deploying documentation - Validating documentation changes - CI documentation checks

See also: mkdocs.yml for configuration

mise run docs-serve¶

Start local documentation server.

What it does: - Builds documentation - Starts local web server - Auto-rebuilds on file changes - Opens browser (optional)

Usage:

mise run docs-serve

Default URL: http://127.0.0.1:8000

When to use: - Writing documentation - Previewing changes before commit - Reviewing documentation locally

Hot reload: Automatically rebuilds when files change

mise run validate-links¶

Validate all documentation links.

What it does: - Checks internal markdown links - Validates external URLs - Reports broken links

Usage:

mise run validate-links

When to use: - Before releases - After major documentation updates - CI link validation

Release Tasks¶

mise run changelog¶

Generate changelog preview with git-cliff.

What it does: - Parses conventional commits - Generates Keep a Changelog format - Shows unreleased changes

Usage:

mise run changelog                # Unreleased changes (default)
mise run changelog --latest       # Latest release
mise run changelog --all          # Full changelog
mise run changelog --help         # Show help

Options: - --unreleased - Show unreleased changes - --latest - Show latest release - --all - Show full changelog history

Output format: Keep a Changelog (based on cliff.toml)

When to use: - Planning releases - Reviewing changes since last version - Generating release notes

See also: cliff.toml for configuration

mise run release¶

Create a new release with automated changelog generation.

What it does: 1. Validates clean working directory 2. Generates changelog with git-cliff 3. Updates CHANGELOG.md 4. Commits changelog 5. Creates annotated git tag 6. Optionally pushes to remote

Usage:

mise run release                    # Interactive version prompt
mise run release v1.8.0             # Explicit version
mise run release --patch            # Auto-bump patch (1.2.3 → 1.2.4)
mise run release --minor            # Auto-bump minor (1.2.3 → 1.3.0)
mise run release --major            # Auto-bump major (1.2.3 → 2.0.0)
mise run release --dry-run          # Preview without committing
mise run release v1.8.0 --push      # Create and push to remote
mise run release --help             # Show full help

Options: - -h, --help - Show help message - -d, --dry-run - Preview changes without creating release - -m, --minor - Auto-bump minor version - -p, --patch - Auto-bump patch version - --major - Auto-bump major version - --push - Push changes and tags to remote - --no-sign - Don't sign the git tag

Workflow: 1. Validate clean working directory 2. Generate changelog 3. Commit CHANGELOG.md 4. Create git tag (signed by default) 5. Optionally push to remote

When to use: - Creating official releases - Version bumps - Automated release workflow

See also: RELEASE.md for release process

Utility Tasks¶

mise run backup¶

Backup current configuration files.

What it does: - Creates timestamped backup directory - Backs up all managed dotfiles - Saves mise tool configuration - Preserves directory structure

Usage:

mise run backup

Backup location: ~/dotfiles-backup-YYYYMMDD-HHMMSS/

What's backed up: - All files managed by chezmoi - mise configuration - Custom scripts

When to use: - Before major changes - Before upgrades - Testing destructive operations - Regular backups (weekly/monthly)

Examples:

mise run backup                              # Basic backup
mise run backup -- --no-ssh-keys             # Exclude SSH keys
mise run backup -- --encrypt                 # Encrypted backup
DOTFILES_BACKUP_DIR=/mnt/usb mise run backup # Custom location

mise run prune¶

Cleanup old mise versions and cache.

What it does: - Removes old tool versions - Cleans mise cache - Frees disk space

Usage:

mise run prune

What's removed: - Unused tool versions - Download cache - Build artifacts

When to use: - Low disk space - After major tool updates - Regular maintenance

Examples:

mise run prune     # Clean unused mise versions and system cache

See also: mise cache clear for manual cache clearing

mise run check-outdated¶

Check for outdated tools and dependencies.

What it does: - Checks all mise-managed tools - Reports available updates - Shows current vs latest versions

Usage:

mise run check-outdated

Output:

Tool      Current    Latest
node      v20.0.0    v20.10.0
python    3.11.0     3.12.0

When to use: - Weekly maintenance - Planning updates - Security audit

Update tools:

mise upgrade        # Upgrade all tools
mise upgrade node   # Upgrade specific tool

Creating Custom Tasks¶

Mise tasks are shell scripts in the mise-tasks/ directory.

Task Template¶

Create a new file: mise-tasks/my-task

#!/usr/bin/env bash
#MISE description="Short description of the task"
#MISE alias="my-task"

set -euo pipefail

# Your task logic here
echo "Running my custom task..."

Make it executable:

chmod +x mise-tasks/my-task

Task Headers¶

Use #MISE comments for task metadata:

• #MISE description="..." - Task description (required)
• #MISE alias="..." - Alternative task name
• #USAGE flag "-f --flag" help="Description" - Define flags

Best Practices¶

1. Use strict mode: set -euo pipefail
2. Add help: Support --help flag
3. Descriptive names: Use clear, action-oriented names
4. Document: Add inline comments for complex logic
5. Test: Ensure idempotent (safe to run multiple times)
6. Keep scripts executable: Shell-based task files must retain +x for mise discovery/launch (use bash scripts/check-shell-script-modes --path mise-tasks --repair to fix drift)

Example: Custom Backup Task¶

#!/usr/bin/env bash
#MISE description="Backup vim plugins"
#MISE alias="backup-vim"

set -euo pipefail

BACKUP_DIR="$HOME/vim-backup-$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

cp -r ~/.config/nvim "$BACKUP_DIR/"
echo "✓ Vim config backed up to $BACKUP_DIR"

Troubleshooting¶

Task Not Found¶

Problem: mise: task 'xyz' not found

Solution: 1. List available tasks: mise tasks 2. Check task file exists: ls mise-tasks/xyz 3. Ensure executable: chmod +x mise-tasks/xyz 4. Repair shell-script execute-bit drift (all tasks): bash scripts/check-shell-script-modes --path mise-tasks --repair 5. Reload mise: mise trust

Task Fails Silently¶

Problem: Task runs but produces no output

Solution: 1. Run with verbose output: MISE_VERBOSE=1 mise run task 2. Check task exit code: echo $? 3. Review task script for errors

Permission Denied¶

Problem: Permission denied when running task (often after syncing across devices/filesystems)

Solution:

# Repair one task
chmod +x mise-tasks/<task-name>

# Or repair all shell-based mise tasks
bash scripts/check-shell-script-modes --path mise-tasks --repair

Note: Public task shims now delegate via bash for better resilience when nested task scripts lose +x, but the task files still need to be executable for mise to discover and launch them directly.

Hook Syntax Deprecated¶

Problem: Warning about # mise syntax

Solution: Update task headers from # mise to #MISE:

# Before
# mise description="Task description"

# After
#MISE description="Task description"

Task Categories¶

By Frequency¶

Daily/Weekly: - doctor - Health checks - test - Run tests - lint - Code quality

As Needed: - install, update - Installation - backup - Before major changes - docs-serve - Documentation work

Rarely: - release - Official releases - rotate-secrets - Security rotation - setup-ssh - New machines

By Audience¶

End Users: - install, update, doctor - backup, uninstall

Contributors: - test, lint, pre-commit - docs-build, docs-serve - changelog, release

Maintainers: - release, rotate-secrets - check-outdated, prune

Related Documentation¶

• README.md - Quick start guide
• CONTRIBUTING.md - Development workflow
• TESTING.md - Test strategy
• RELEASE.md - Release process
• SECRETS.md - Secrets management
• TROUBLESHOOTING.md - Common issues

Quick Command Reference¶

# Installation
mise run install                    # Install dotfiles
mise run update                     # Update everything

# Health & Testing
mise run doctor                     # Check system health
mise run test                       # Run test suite
mise run lint                       # Run linters

# Development
mise run docs-serve                 # Preview documentation
mise run profile                    # Profile shell startup

# Secrets
mise run setup-secrets              # Initialize encryption
mise run setup-ssh                  # Generate SSH keys

# Release
mise run changelog                  # Preview changelog
mise run release --patch            # Create patch release

# Utilities
mise run backup                     # Backup configuration
mise run check-outdated             # Check for updates
mise run prune                      # Clean up cache

# List all tasks
mise tasks

# Get task help
mise run <task> --help