macbot-cli 0.1.0
macOS automation CLI for AI agents and developers
Requires Python: >=3.9
Keywords: ai-agent, applescript, automation, cli, macos

# 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

```bash
pip install macbot-cli
```

## Quick Start

```bash
# 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
```bash
macbot notify "Title" "Message"
macbot notify "Alert" --subtitle "Warning" --sound Ping
```

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

### Text-to-Speech
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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:

```bash
macbot --json wifi status
```

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

## Optional Dependencies

Some commands require additional tools:

```bash
# Display brightness
brew install brightness

# Bluetooth control
brew install blueutil

# Audio device switching
brew install switchaudio-osx
```

## For AI Agents

See [SKILL.md](SKILL.md) for agent-optimized documentation.

## License

MIT