Mac-CLI Deployment & Usage Guide

Prerequisites

Operating System: macOS (10.12 Sierra or later recommended)
Privileges: Administrator access (requires sudo to install to /usr/local/bin/)
Terminal: Any terminal emulator (Terminal.app, iTerm2, Hyper, etc.)
Dependencies (auto-installed if missing):
- Homebrew
- Git
- Pipe Viewer (pv)
Network: Active internet connection for installation and updates

Installation

Standard Installation

Run the automated installer using either curl or wget:

Via curl:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/guarinogabriel/mac-cli/master/mac-cli/tools/install)"

Via wget:

sh -c "$(wget https://raw.githubusercontent.com/guarinogabriel/mac-cli/master/mac-cli/tools/install -O -)"

Post-Installation

Restart your terminal or run source ~/.bash_profile (or ~/.zshrc for Zsh users)
Verify installation:
```
mac help
```
Complete the configuration wizard that appears on first run to set preferences

Alternative: Manual Clone (for development)

git clone https://github.com/guarinogabriel/Mac-CLI.git
cd Mac-CLI/mac-cli
# Manual installation would require copying scripts to /usr/local/bin and setting permissions

Configuration

Initial Configuration

The interactive configuration wizard runs automatically during first installation. It will prompt you to:

Confirm installation paths
Select preferred default behaviors
Set optional aliases

Manual Configuration

Edit the main configuration file directly:

sudo nano /usr/local/bin/mac

Configuration file location: /usr/local/bin/mac

Plugin Architecture

Custom commands can be added by creating new files in the plugins directory structure (located in the git repository at /mac-cli/plugins/). To add custom functionality:

Navigate to the cloned repository
Add shell scripts to the appropriate category folder under mac-cli/plugins/
Re-run the installer or manually symlink your additions

Build & Run

No Build Step Required

Mac-CLI is a collection of executable shell scripts. No compilation or build process is necessary.

Running Commands

All commands follow the pattern:

mac <command> [arguments]

Essential first-run commands:

# View all available commands
mac help

# Update macOS and package managers
mac update

# Check system information
mac info

# Test network utilities
mac speedtest
mac ip:public

Common workflow examples:

# System maintenance
mac update
mac restart

# File operations
mac folders:list
mac find:biggest-files

# Network management
mac wifi:scan
mac dns:flush

Development Mode

To modify and test changes locally:

Edit files in your cloned repository
Test individual plugin scripts: bash mac-cli/plugins/general/custom-script.sh
Reinstall to apply changes system-wide: sh -c "$(curl -fsSL https://raw.githubusercontent.com/guarinogabriel/mac-cli/master/mac-cli/tools/update)"

Deployment

Team/Enterprise Deployment

Silent Installation Script: For mass deployment across developer machines, wrap the installer in a deployment script:

#!/bin/bash
# deploy-mac-cli.sh
if ! command -v mac &> /dev/null; then
    echo "Installing Mac-CLI..."
    sh -c "$(curl -fsSL https://raw.githubusercontent.com/guarinogabriel/mac-cli/master/mac-cli/tools/install)" -- --batch
    echo "Mac-CLI installed successfully"
else
    echo "Mac-CLI already installed, updating..."
    sh -c "$(curl -fsSL https://raw.githubusercontent.com/guarinogabriel/mac-cli/master/mac-cli/tools/update)"
fi

MDM (Mobile Device Management) Deployment:

Package the installer as a .pkg file using Packages or munkipkg

Deploy via Jamf Pro, Kandji, or Fleet:

# Post-install script for MDM
sh -c "$(curl -fsSL https://raw.githubusercontent.com/guarinogabriel/mac-cli/master/mac-cli/tools/install)"

CI/CD Integration: Use in GitHub Actions or other CI pipelines for macOS runners:

# .github/workflows/macos-setup.yml
- name: Install Mac-CLI
  run: |
    sh -c "$(curl -fsSL https://raw.githubusercontent.com/guarinogabriel/mac-cli/master/mac-cli/tools/install)"
    source ~/.bash_profile
    
- name: Run system diagnostics
  run: |
    mac info
    mac battery

Update Management

Manual Update:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/guarinogabriel/mac-cli/master/mac-cli/tools/update)"

Automated Updates: Add to your shell profile (~/.zshrc or ~/.bash_profile) for weekly update checks:

# Check for Mac-CLI updates every 7 days
if [ ! -f ~/.mac-cli-last-update ] || [ "$(find ~/.mac-cli-last-update -mtime +7)" ]; then
    echo "Checking for Mac-CLI updates..."
    sh -c "$(curl -fsSL https://raw.githubusercontent.com/guarinogabriel/mac-cli/master/mac-cli/tools/update)" 2>/dev/null
    touch ~/.mac-cli-last-update
fi

Uninstallation

sh -c "$(curl -fsSL https://raw.githubusercontent.com/guarinogabriel/mac-cli/master/mac-cli/tools/uninstall)"

Troubleshooting

Command Not Found

Issue: mac: command not found after installation

Solutions:

Reload shell configuration:

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

Check PATH:

echo $PATH | grep /usr/local/bin

If missing, add to ~/.zshrc or ~/.bash_profile:

export PATH="/usr/local/bin:$PATH"

Permission Denied

Issue: Permission denied when running mac commands

Solution:

sudo chmod +x /usr/local/bin/mac
sudo chmod -R +x /usr/local/bin/mac-cli/

Dependency Installation Failures

Issue: Homebrew, Git, or pv not found after installation

Solution: Manually install dependencies:

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install other dependencies
brew install git pv

Configuration File Corruption

Issue: Commands behaving unexpectedly after manual config edits

Solution: Restore default configuration by reinstalling:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/guarinogabriel/mac-cli/master/mac-cli/tools/update)"

Plugin Commands Not Working

Issue: Custom or specific category commands fail