Installation Guide
Relevant source files
The following files were used as context for generating this wiki page:
The spoof project is a cross-platform Node.js command-line interface (CLI) tool designed to modify Media Access Control (MAC) addresses on macOS, Linux, and Windows. This guide outlines the various methods available for installing and setting up the tool, ranging from automated scripts for macOS to manual global installation via package managers.
Sources: README.md:1-17, CLAUDE.md:7-12
Prerequisites
Before installing spoof, ensure your system meets the following requirements:
- Runtime: Node.js version 24 or higher is required.
- Package Manager: The project uses Yarn 4 (
yarn@4.14.1) for development, though it can be installed globally vianpm. - Permissions: Administrative or
sudoprivileges are required for the tool to execute MAC address changes on all supported platforms.
Sources: package.json:115-117, CLAUDE.md:10-12, README.md:46-48
Automated Installation (macOS Only)
For macOS users, a standalone helper script is provided to automate the setup of the entire environment, including dependencies.
curl -fsSL https://raw.githubusercontent.com/TheJACKedViking/spoof/main/scripts/mac-randomize.sh | bash
Automation Logic Flow
The script performs several environmental checks and installations sequentially to ensure the tool can run.
The script uses mktemp to create a secure temporary directory for the build process and handles terminal settings for an interactive interface picker.
Sources: scripts/mac-randomize.sh:13-90, README.md:31-40
Global Installation
For general use on any supported platform, spoof can be installed globally through standard Node.js package managers.
| Manager | Command | Result |
|---|---|---|
| npm | npm install -g spoof | Installs spoof to system PATH |
| Yarn | yarn global add spoof | Installs spoof to system PATH |
| npx | npx spoof <command> | Runs tool without permanent installation |
Sources: README.md:52-65
Developer / Source Installation
Developers wishing to contribute or modify the tool can install from the source repository.
Build and Setup Sequence
Build Commands
The following scripts in package.json are critical for the build process:
yarn install: Installs dependencies includingchalk,minimist, andwinreg.yarn build: Executestsupfor bundling andtsc --emitDeclarationOnlyfor type definitions.yarn clean: Removesnode_modules,dist, and yarn caches.
Sources: package.json:69-82, CLAUDE.md:16-24, README.md:67-74
Platform-Specific Setup Notes
| Platform | Underlying Tooling | Special Requirements |
|---|---|---|
| macOS | networksetup, airport | Requires sudo. Wi-Fi must disassociate before change. |
| Linux | ip (iproute2), ifconfig | Requires sudo. Can prefer legacy ifconfig via flag. |
| Windows | ipconfig, winreg | Must run from Administrator shell. |
Sources: README.md:78-84, CLAUDE.md:68-73
Summary
Installation of spoof is flexible, supporting automated setup for macOS via mac-randomize.sh, global distribution via npm, and source-based builds using Yarn 4. Regardless of the method, the tool requires Node.js 24+ and elevated system permissions to perform its core function of spoofing network hardware addresses.
Sources: README.md:46-54, package.json:116