macbot-cli 0.1.0

macOS automation CLI for AI agents and developers

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