# How to Install Mole on macOS: Complete Setup Guide

> Install Mole on macOS easily with a single Bash command. Get the complete setup guide for the latest release and add Mole to your PATH.

- Repository: [Tw93/Mole](https://github.com/tw93/Mole)
- Tags: getting-started
- Published: 2026-03-20

---

**You can install Mole on macOS by running a single Bash one-liner that downloads the installer from [`bin/installer.sh`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/bin/installer.sh). This command downloads the script and pipes it directly to Bash:

```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:**

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

```

2. **Make it executable:**

```bash
chmod +x /tmp/mole-installer.sh

```

3. **Execute the installer:**

```bash
/tmp/mole-installer.sh

```

## What the Installer Actually Does

When you run either installation method, the [`install.sh`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/install.sh) with a thin wrapper at [`bin/installer.sh`](https://github.com/tw93/Mole/blob/main/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:

```bash
mole --version

```

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

```bash
source ~/.zshrc  # or ~/.bash_profile

```

Test basic functionality with the status command:

```bash
mole status

```

## Optional: Homebrew Integration

While the script installation provides `mole update` functionality via [`bin/update.sh`](https://github.com/tw93/Mole/blob/main/bin/update.sh), you can also register Mole with Homebrew for semantic versioning control:

```bash
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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/install.sh) to ensure compatibility with the script's system maintenance features.