How to Install Mole on macOS: Complete Setup Guide

You can install Mole on macOS by running a single Bash one-liner that downloads the installer from bin/installer.sh, extracts the release to ~/.local/mole, and symlinks the commands into your PATH.

Mole is a fast, script-driven maintenance utility for macOS that cleans caches, uninstalls applications, and manages Homebrew packages. According to the tw93/Mole source code, the entire installation is handled by pure Bash scripts with zero external dependencies, making it compatible with any Mac running macOS 10.15 or later.

Prerequisites

Before installing Mole, ensure your system meets the minimum requirements. The installer script in install.sh explicitly checks for macOS version 10.15 (Catalina) or newer.

• Operating System: macOS 10.15+
• Shell: Bash or Zsh (standard on macOS)
• Permissions: Standard user account (no root required)

Installation Methods

You have two ways to install Mole: a quick one-liner for immediate setup, or manual steps if you prefer to inspect the code first.

One-Liner Install (Recommended)

The fastest way to install Mole uses the official installer wrapper located at bin/installer.sh. This command downloads the script and pipes it directly to Bash:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/tw93/Mole/main/bin/installer.sh)"

This single command executes the full installation pipeline: platform detection, release download, extraction, and PATH setup.

Manual Step-by-Step Install

If you prefer to review the installer before execution, download and run it manually:

1. Download the installer script:

curl -fsSL https://raw.githubusercontent.com/tw93/Mole/main/bin/installer.sh -o /tmp/mole-installer.sh

2. Make it executable:

chmod +x /tmp/mole-installer.sh

3. Execute the installer:

/tmp/mole-installer.sh

What the Installer Actually Does

When you run either installation method, the install.sh script performs a deterministic setup sequence. Examining the source code reveals the following steps:

1. Platform Detection – Verifies macOS ≥ 10.15
2. Download – Fetches the latest release archive from GitHub
3. Extraction – Unpacks files into ~/.local/mole
4. Symlinking – Creates links in ~/.local/bin for mole, mole-status, mole-clean, and other entry points
5. PATH Configuration – Ensures the symlink directory is accessible (creates or appends to shell profile if needed)
6. Optional Homebrew Tap – Offers to register the tw93/mole tap for future upgrades

All logic resides in install.sh with a thin wrapper at bin/installer.sh that handles the initial download. The entire toolchain is Bash-native and requires no Node.js, Python, or Go runtime.

Verify the Installation

After installation completes, confirm Mole is accessible by checking its version:

mole --version

You should see the current release number printed to stdout. If you receive a "command not found" error, reload your shell configuration:

source ~/.zshrc  # or ~/.bash_profile

Test basic functionality with the status command:

mole status

Optional: Homebrew Integration

While the script installation provides mole update functionality via bin/update.sh, you can also register Mole with Homebrew for semantic versioning control:

brew tap tw93/mole
brew install mole

This creates a managed installation that respects brew upgrade mole workflows. The update logic in lib/manage/update.sh handles GitHub release checking and binary replacement regardless of which installation method you chose initially.

Summary

• Mole installs via pure Bash using bin/installer.sh or the one-liner equivalent
• Installation location: ~/.local/mole with symlinks in ~/.local/bin
• Zero dependencies: No runtimes required beyond standard macOS tools
• System requirements: macOS 10.15 or later
• Post-install verification: Run mole --version and mole status
• Upgrade paths: Use mole update or brew upgrade mole if you added the tap

Frequently Asked Questions

Where does Mole install its files on macOS?

Mole extracts its core distribution to ~/.local/mole and creates symlinks for executable commands in ~/.local/bin (or a similar PATH-accessible directory). This user-local approach avoids permission conflicts and keeps the system directories clean.

Can I install Mole without Homebrew?

Yes. The standard installation from install.sh requires no Homebrew dependency. Homebrew integration is entirely optional and only provided as a convenience for users who prefer brew upgrade workflows for package management.

How do I update Mole after installation?

You have two options: run mole update (implemented in bin/update.sh), which checks GitHub releases and replaces local binaries automatically, or use brew upgrade mole if you registered the tw93/mole tap during initial setup.

What macOS versions are supported?

The installer explicitly requires macOS 10.15 (Catalina) or newer. This requirement is hardcoded in the platform detection logic within install.sh to ensure compatibility with the script's system maintenance features.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}