macbot

macOS automation CLI for AI agents and developers. Control notifications, clipboard, windows, audio, display, and more from the command line with optional JSON output.

Installation

pip install macbot-cli

Quick Start

# Send a notification
macbot notify "Build Complete" "All tests passed"

# Get/set clipboard
macbot clipboard get
macbot clipboard set "Hello, World!"

# Text-to-speech
macbot say "Hello from macbot" --voice Daniel

# Take a screenshot
macbot screenshot ~/Desktop/screen.png

# Volume control
macbot audio volume 50
macbot audio mute

# WiFi control
macbot wifi status
macbot wifi networks

Commands

Notifications

macbot notify "Title" "Message"
macbot notify "Alert" --subtitle "Warning" --sound Ping

Clipboard

macbot clipboard get         # Get contents
macbot clipboard set "text"  # Set contents
macbot clipboard clear       # Clear clipboard

Text-to-Speech

macbot say "Hello"                    # Default voice
macbot say "British" --voice Daniel   # Specific voice
macbot say "Fast" --rate 300          # Faster speech
macbot say "Save" --output speech.aiff # Save to file
macbot say "" --list-voices           # List voices

Screenshots

macbot screenshot                  # Desktop with timestamp
macbot screenshot screen.png       # Specific file
macbot screenshot --clipboard      # To clipboard
macbot screenshot --window         # Front window
macbot screenshot --interactive    # Select region
macbot screenshot --delay 3        # 3 second delay

Window Management

macbot window list                        # List all windows
macbot window list --app Safari           # Filter by app
macbot window focus Safari                # Focus app
macbot window focus "VS Code" -t project  # Focus specific window
macbot window move Safari -x 0 -y 0 -w 1200 -h 800
macbot window minimize Safari

Applications

macbot apps list                    # All installed apps
macbot apps list --running          # Running apps only
macbot apps launch Safari           # Launch app
macbot apps launch Safari -b        # Launch in background
macbot apps quit Safari             # Quit app
macbot apps quit "Frozen" --force   # Force quit
macbot apps hide Safari             # Hide app
macbot apps show Safari             # Show/unhide app

Audio

macbot audio volume              # Get volume
macbot audio volume 50           # Set to 50%
macbot audio mute                # Mute
macbot audio mute --toggle       # Toggle mute
macbot audio unmute              # Unmute
macbot audio devices             # List devices
macbot audio output "Speakers"   # Set output device
macbot audio input "Microphone"  # Set input device

Display Brightness

macbot brightness          # Get brightness
macbot brightness 0.7      # Set to 70%
macbot brightness 0.5 -d 1 # Set external display

Requires: brew install brightness

WiFi

macbot wifi status           # Status and IP
macbot wifi on               # Turn on
macbot wifi off              # Turn off
macbot wifi networks         # List available
macbot wifi connect "SSID" --password "pass"
macbot wifi disconnect

Bluetooth

macbot bluetooth status              # Power state
macbot bluetooth on                  # Turn on
macbot bluetooth off                 # Turn off
macbot bluetooth devices             # List devices
macbot bluetooth devices --connected # Connected only
macbot bluetooth connect XX-XX-XX-XX-XX-XX
macbot bluetooth disconnect XX-XX-XX-XX-XX-XX

Requires: brew install blueutil

JSON Output

All commands support --json for machine-readable output:

macbot --json wifi status

{
  "interface": "en0",
  "power": "on",
  "network": "MyNetwork",
  "ip_address": "192.168.1.100",
  "connected": true,
  "success": true
}

Optional Dependencies

Some commands require additional tools:

# Display brightness
brew install brightness

# Bluetooth control
brew install blueutil

# Audio device switching
brew install switchaudio-osx

For AI Agents

See SKILL.md for agent-optimized documentation.

License

MIT