❄️ .dotfiles

Declarative, Reproducible macOS System Architecture & Custom Tooling

A fully declarative macOS workstation setup engineered with Nix Flakes, Home Manager, nix-homebrew, and nara-cli—a bespoke Go-based workflow engine.

---

📌 Table of Contents

• Overview
• System Architecture
• nara-cli Workflow Engine
• Software & Tooling Stack
• Installation & Bootstrapping
• Project Templates
• Repository Structure

---

🔍 Overview

This repository contains the complete configuration for my personal Apple Silicon Mac environment. Every application, macOS setting, shell utility, and project template is declared immutably using Nix Flakes.

Key Highlights

• Zero Imperative Drift: Rebuilding the configuration enforces the exact state across system defaults, user packages, and shell aliases.
• Bespoke Go CLI (nara-cli): Custom CLI built to automate permission fixes, system rebuilds, diagnostics, and workspace scaffolding.
• Automated Dev Environments: Pre-configured direnv + nix-direnv integration for instant, zero-pollution per-directory development shells.

---

🏗️ System Architecture

graph TD
    A["flake.nix"] --> B["nix-darwin"]
    A --> C["home-manager"]
    A --> D["nara-cli"]

    B --> E["macOS System Defaults & Keymaps"]
    B --> F["nix-homebrew & GUI Casks"]

    C --> G["Zsh, Starship & Modern CLI Utilities"]
    C --> H["Config Symlinks: Neovim, Ghostty, AeroSpace"]

    D --> I["nara rebuild / sync"]
    D --> J["nara doctor"]
    D --> K["nara new"]
    D --> L["nara clean"]
    D --> M["nara run"]
    D --> N["nara stats"]
    D --> O["nara audit"]
    D --> P["nara share"]
    D --> Q["nara upgrade"]

Loading

---

⚡ nara-cli Workflow Engine

nara is a high-performance CLI written in Go to eliminate boilerplate commands and maintain environment health.

Commands Reference

Command	Usage	Description
rebuild / sync	nara rebuild	Automatically fixes .git permissions, stages changes, and executes darwin-rebuild switch.
upgrade	nara upgrade	Full system update: updates Nix flake locks, upgrades Homebrew casks, rebuilds, & cleans.
doctor	nara doctor	Runs diagnostic health checks on $PATH binaries, user ID permissions, and environment variables.
new	nara new <app>	Scaffolds a new project directory using the default Nix Flake template, initializes Git, and enables direnv.
clean	nara clean [--all]	Performs garbage collection on old Nix generations and executes nix store optimise to hard-link duplicate files.
run	nara run <pkg>	Runs any package from nixpkgs ephemerally on-demand without installing it.
stats	nara stats	Displays a colorful ASCII system, Nix store size, and Git status dashboard.
audit	nara audit	Scans macOS battery status, top CPU/RAM hogs, and active Homebrew services.
share	nara share [file]	Serves files/folders over Wi-Fi with chunked HTTP byte-range streaming & terminal QR codes.
version	nara version	Prints current nara-cli release version.

Compiling & Installing nara-cli

cd ~/.dotfiles/nara-cli
go build -o ~/.local/bin/nara main.go

---

💻 Software & Tooling Stack

Core System & Window Management

• Window Manager: AeroSpace (Tiling Window Manager for macOS)

  • Configured with custom global Alt keybindings (Alt+Enter Ghostty, Alt+F Fullscreen toggle, Alt+Shift+Space Float toggle, Alt+H/J/K/L Vim navigation)

• Terminal Emulator: Ghostty

• Browser: Google Chrome / Arc

• Launcher: Raycast

• Container Runtime: OrbStack

Modern Shell & CLI Utilities

• Shell: Zsh configured via Home Manager with autosuggestions, syntax-highlighting, and history-substring-search.
• Prompt: Starship
• File & Text Navigation:
  • eza — Modern, colorized ls replacement with git status integration.
  • bat — Syntax-highlighted cat replacement with line numbering.
  • zoxide — Smart cd alternative powered by frecency algorithm.
  • fzf — Fuzzy finder with native Zsh keybindings (Ctrl+R, Ctrl+T).
  • yazi — Blazing-fast terminal file manager written in Rust.
  • ripgrep & fd — Fast file content and path search utilities.
  • lazygit — Terminal UI for Git commands.

---

🚀 Installation & Bootstrapping

Follow these step-by-step instructions to set up a fresh macOS machine with this configuration from scratch:

1. Install Xcode Command Line Tools

Required for git and system build utilities. Run in Terminal:

xcode-select --install

Follow the on-screen popup to complete installation.

---

2. Install Nix Package Manager

We recommend the Determinate Systems Nix Installer, which automatically configures Nix Flakes and multi-user support:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

Note: After installation completes, close and reopen your terminal session (or run . /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh).

---

3. Clone Repository

Clone this repository to ~/.dotfiles:

git clone https://github.com/Aneeshie/dotfiles.git ~/.dotfiles
cd ~/.dotfiles

---

4. Execute Bootstrap Rebuild (nix-darwin)

Run the bootstrap script to link your configuration and build the initial nix-darwin environment:

./rebuild.sh

On the first run, rebuild.sh will automatically detect that darwin-rebuild is not yet in your $PATH and bootstrap nix-darwin via nix run.

---

5. Build & Install nara-cli

Ensure ~/.local/bin exists and compile the custom CLI:

mkdir -p ~/.local/bin
cd ~/.dotfiles/nara-cli
go build -o ~/.local/bin/nara main.go

Verify your setup by running:

nara doctor

---

📦 Project Templates

This repository exposes Nix Flake templates for rapid workspace initialization.

To initialize a new development workspace manually:

nix flake init -t ~/.dotfiles

Or instantly via nara-cli:

# Default boilerplate
nara new my-project

# Language-specific templates
nara new my-rust-app rust
nara new my-go-service go
nara new my-script python
nara new my-java-app java

---

📂 Repository Structure

.dotfiles/
├── configuration.nix      # macOS system defaults, hidutil keymaps & Homebrew casks
├── home.nix               # Home Manager configuration, CLI utilities & dotfiles symlinks
├── flake.nix              # Main Nix Flake definition & exported project templates
├── rebuild.sh             # Initial system bootstrap shell script
├── templates/             # Flake templates for new workspaces
│   ├── default/           # Default devShell & .envrc template
│   ├── rust/              # Rust template (cargo, rustc, clippy, rust-analyzer)
│   ├── go/                # Go template (go, gopls, gotools, golangci-lint)
│   ├── python/            # Python 3 template (python3, pip, venv, pyright, black)
│   └── java/              # Java template (JDK 17, maven, gradle)
└── nara-cli/              # Custom Go CLI workflow tool
    ├── main.go            # Entry point & subcommand router
    ├── go.mod             # Go module definition
    └── cmd/               # Subcommand implementations
        ├── rebuild.go     # `nara rebuild` logic
        ├── doctor.go      # `nara doctor` diagnostic suite
        ├── new.go         # `nara new` scaffolding engine
        ├── clean.go       # `nara clean` Nix storage optimizer
        ├── run.go         # `nara run` ephemeral package runner
        ├── stats.go       # `nara stats` system dashboard
        ├── audit.go       # `nara audit` performance & battery scanner
        ├── share.go       # `nara share` local Wi-Fi file server & QR code generator
        └── upgrade.go     # `nara upgrade` full macOS system update pipeline

---

Crafted with ❤️ by Aneeshie