Getting Started

This guide walks you through installing and activating these dotfiles on your system.

There are two ways in. Deploy a published release if you only want to run these dotfiles; clone the repository if you intend to change them — the release archive carries no build tooling.

Quick Start (clone)

git clone https://github.com/arttet/dotfiles.git
cd dotfiles
mise install
mise run deploy:sync:config
mise run deploy:check    # Preview what will be linked
mise run deploy:apply
mise install             # Install the deployed global toolchain
mise run setup           # Shell caches, GitHub extensions, telemetry, and agent skills

Quick Start (release)

Every tag publishes an archive alongside an SBOM, a license inventory, a manifest naming the commit it was built from, and checksums. Check it before you trust it:

gh release download --repo arttet/dotfiles
sha256sum --check checksums.sha256
gh attestation verify dotfiles.tar.gz --repo arttet/dotfiles

mkdir dotfiles && tar -xzf dotfiles.tar.gz -C dotfiles && cd dotfiles
dotter deploy --verbose --dry-run
dotter deploy --verbose --force

The archive unpacks to dotfiles/ plus .dotter/, which is the layout dotter expects, and the vendored plugins are already inside it — do not run vendir sync there. INSTALL.md ships in the archive with the offline deployment instructions.

Prerequisites

• mise — installs every pinned tool below with mise install
• dotter — the deployer
• just (optional, for convenience commands)
• vendir (to sync external plugins)

Note: The tools configured in these dotfiles (yazi, eza, Zellij, etc.) are assumed to be installed separately via your package manager.

Deployment

dotter is the only deployer, on every platform — it handles Windows-specific paths and profiles:

# Preview changes without applying
mise run deploy:check

# Deploy dotfiles
mise run deploy:apply

# Remove deployed links
mise run deploy:undeploy

The just recipes of the same name are convenience shims over these mise tasks — the mise tasks are what CI runs. GNU Stow is not used and the tree is not laid out for it.

What gets deployed is selected in .dotter/local.toml by listing packages. A fresh clone ships:

packages = ["default"]

default is a group (configured in .dotter/global.toml) that pulls in agent (Claude Code, Codex, Kimi Code, OpenCode), dev (mise), editor (Helix, Zed), shell (Bash, PowerShell, Zsh), and terminal (Alacritty, Windows Terminal). The wallpapers package is deliberately outside default — add it to opt into the ~1.1 GB background collections:

packages = ["default", "wallpapers"]

Sync External Dependencies

Some configs rely on vendored plugins and themes:

mise run deploy:sync            # plugins and wallpapers (~1.1 GB)
mise run deploy:sync:config     # plugins only, which is what CI runs

This updates external resources managed by vendir (Alacritty themes, Yazi plugins, etc.). Do not edit these files manually.

Directory Overview

dotfiles/
├── .config/          # Tool configurations (nvim, shells, git, etc.)
│   ├── bash/
│   ├── nushell/
│   ├── nvim/
│   └── shell/shell.d/ # Shared aliases and functions
├── .bashrc
├── .bash_profile
├── .zshenv
└── ...

nixos/                # NixOS and Home Manager configs
misc/                 # Supplementary files and justfile modules

Useful Commands

mise tasks                     # List all available tasks
mise run fmt:write             # Format all code
mise run lint:all              # Run all linters
(cd docs && aube run docs:dev) # Start documentation dev server
mise run bench:all             # Benchmark shell startup times
mise run artifact:dotfiles:all # Build a release set locally

Next Steps

• Shells: Primary shell is Nushell. Bash and Zsh configs are also provided.
• Editor: Neovim 0.12+ on the built-in vim.pack manager — start with nvim.
• Multiplexer: Zellij (zellij) or Tmux (tmux, prefix Ctrl + A).