CLI Overview & Global Flags

Relevant source files

The following files were used as context for generating this wiki page:

• src/cli.ts
• src/index.ts
• src/oui.ts
• test/cli.test.ts
• README.md
• package.json

The spoof CLI is a Node.js-based utility designed to manage and spoof Media Access Control (MAC) addresses across macOS, Linux, and Windows platforms. It provides a user-friendly interface for listing network adapters, setting specific MAC addresses, and generating randomized addresses based on vendor OUI (Organizationally Unique Identifier) data.

The CLI serves as a wrapper around a core TypeScript API, utilizing system-level commands like networksetup, ifconfig, ip, and netsh to perform hardware-level changes. It supports structured JSON output for automation, dry-run capabilities for safety, and detailed diagnostic logging through global flags.

Sources: src/cli.ts:1-10, README.md:10-25, src/index.ts:50-70

Command Architecture & Execution Flow

The CLI entry point uses minimist for argument parsing and an asynchronous Initialization function to route commands. The execution flow follows a consistent pattern: parsing arguments, validating flags, configuring global tool preferences (like prefer-ifconfig), and then executing the specific command logic.

CLI Initialization Flow

The following diagram illustrates how the CLI processes a user request from input to command execution.

The CLI utilizes a structured ParsedArgs interface to handle options and an OperationResult interface to track the success or failure of multi-device operations.

Sources: src/cli.ts:13-50, src/cli.ts:98-135

Global Flags and Configuration

The spoof utility includes several global flags that modify the behavior of various commands, such as filtering output, changing randomization logic, or toggling diagnostic modes.

Flag	Alias	Type	Description
--wifi	N/A	Boolean	Filters the list command to show only wireless interfaces.
--local	N/A	Boolean	Sets the locally administered bit (bit 1 of first byte) on randomized MACs.
--vendor	N/A	String	Randomizes using a specific vendor's OUI prefix (e.g., apple, samsung).
--prefer-ifconfig	N/A	Boolean	Forces the use of ifconfig instead of ip on Linux systems.
--format	N/A	String	Output format. Currently only json is supported.
--dry-run	-n	Boolean	Shows intended changes without applying them. Returns exit code 2 if it would fail.
--verbose	-v	Boolean	Enables detailed diagnostic logging to stderr.
--quiet	-q	Boolean	Suppresses all non-essential output.
--timeout	N/A	Number	Operation timeout in milliseconds (default: 30000ms).
--version	N/A	Boolean	Displays the current package version.

Flag Validation Logic

The CLI enforces strict validation for certain flag combinations. For instance, --verbose and --quiet are mutually exclusive. If both are provided, the CLI outputs an error and exits with code 1. Similarly, if --prefer-ifconfig is detected, the CLI calls spoof.setPreferIfconfig(true) before any other operation.

Sources: src/cli.ts:40-90, src/cli.ts:160-185, README.md:120-145

Output Management

The CLI provides two primary output modes: Human-Readable (Text) and Structured (JSON). Output is managed through centralized functions that respect the --quiet and --format=json flags.

Structured JSON Output

When the --format=json flag is used, all standard console logging is suppressed in favor of a single JSON object. This object includes metadata such as the platform, version, and a success status.

function outputJson(data: Record<string, unknown>): void {
  const response = {
    success: true,
    ...data,
    platform: process.platform,
    version: (require('../package.json') as { version: string }).version
  }
  console.log(JSON.stringify(response, null, 2))
}

Sources: src/cli.ts:107-116, test/cli.test.ts:255-275

Core Command Details

Management Commands

• list (ls): Scans the system for network interfaces. On macOS, it parses networksetup -listallhardwareports. On Linux, it defaults to ip link show. On Windows, it uses ipconfig /all.
• set: Requires a MAC address and at least one device. It validates the MAC format before attempting the change.
• randomize: Generates a random MAC. If --vendor is provided, it uses oui.randomizeAsVendorWithInfo to select a prefix from the oui.json database.
• reset: Attempts to restore the hardware "burned-in" MAC address.

Utility Commands

• normalize: Converts various MAC formats (Cisco-style, dash-separated, or no-separator) into the canonical XX:XX:XX:XX:XX:XX format.
• lookup: Queries the internal OUI database to identify the manufacturer of a given MAC address.
• vendors: Performs a fuzzy search of the OUI database using Levenshtein distance to find matching manufacturers.

Sources: src/cli.ts:137-160, src/index.ts:100-150, src/oui.ts:130-160

Safety and Permission Handling

The CLI implements safeguards to prevent accidental system changes and handles permission requirements:

1. Dry-Run Mode: Processes the entire command logic, including interface discovery and MAC generation, but skips the final hardware write. It logs the intended action with a [DRY-RUN] prefix.
2. Root/Admin Check: For set, randomize, and reset, the CLI checks for elevated privileges. On Unix-like systems, it verifies process.getuid() === 0. On Windows, the underlying netsh command requires an Administrator shell.
3. Exit Codes:
   • 0: Success.
   • 1: General error (e.g., permission denied, invalid MAC).
   • 2: Dry-run failure (e.g., specified device not found).

Sources: src/cli.ts:200-220, src/cli.ts:365-375, test/cli.test.ts:300-325

Conclusion

The spoof CLI provides a robust interface for hardware-level network configuration by abstracting platform-specific system tools into a unified command set. Through its extensive use of global flags, it supports both interactive manual use and automated scripting via structured JSON output and comprehensive exit code signaling.

Sources: src/cli.ts:1-50, README.md:1-20