mac

Calendar, Reminders, Contacts, Mail, Messages and Notes, on the command line. One binary, built for AI agents and the humans who drive them. Every command has --json, stable exit codes, and IDs you can trust.

❯git clone https://github.com/31Carlton7/mac-cli.git && cd mac-cli && make install View on GitHub
mac — zsh 

  






  
Native frameworks, not screen scraping. Calendar, Reminders and Contacts run on EventKit and Contacts: millisecond calls, typed errors, stable IDs. Mail, Messages and Notes go through AppleScript and a read-only Messages database, because Apple ships no public API for them, and mac is honest about the difference.






  

    

      
Calendar

      
Dates take ISO, naturals and offsets.

      
❯ mac calendar list --from today --to +7d
❯ mac calendar add "Dentist" --at "tomorrow 2pm"

    

    

      
Reminders

      
Add, complete and edit across every list.

      
❯ mac reminders add "Buy milk" --list Groceries
❯ mac reminders complete <id>

    

    

      
Contacts

      
Resolve a name to a handle before you send.

      
❯ mac contacts find "Sarah"
❯ mac contacts find "Sarah" --json

    

    

      
Mail

      
Drafting is preferred over sending, by design.

      
❯ mac mail unread --limit 10
❯ mac mail draft --to a@b.com --subject "Hi"

    

    

      
Messages

      
Read history, send texts. Exact handles only.

      
❯ mac messages history +15551234567
❯ mac messages send +1555… "On my way"

    

    

      
Notes

      
List, search, add and append by folder.

      
❯ mac notes search "brunch"
❯ mac notes append <id> "one more thing"

    

  






  
Next

  

    Music
    TV
    Shortcuts
    Calls
  

  
In development for v0.4.0, not in the current release. Shortcuts is the escape hatch: wrap an app that has no scripting surface of its own in a Shortcut, and agents can drive it too.






  
Built for agents, kind to humans. --json on every command, with sorted keys, ISO 8601 dates and stable schemas. Mutations take exact IDs only, errors are actionable one-liners on stderr, and exit codes are something an agent can actually branch on.

  

    0 success
    1 not found
    2 permission denied
    64 usage error
  






  

    

      
      mac — zsh
    

    
❯ mac contacts find "Sarah" --json
{
  "emails": ["sarah@example.com"],
  "id": "AB1C2D3E-4F56-7890-A1B2-C3D4E5F6A7B8",
  "name": "Sarah Chen",
  "phones": ["+15551234567"]
}
❯ mac messages send +15551234567 "Brunch at 11?"
✓ sent to +15551234567

  






  
Permissions, diagnosed. macOS prompts once per capability, and mac doctor reports every grant (Calendar, Reminders and Contacts access, Automation consent, Full Disk Access) with fix steps when something is missing. No silent failures, no mystery errors.






  

    

      
      mac doctor — zsh
    

    
❯ mac doctor
✓ Calendar    access granted
✓ Reminders   access granted
✓ Contacts    access granted
✓ Mail        Automation consent granted
✗ Messages    Full Disk Access missing for Terminal
              → System Settings › Privacy & Security › Full Disk Access
✓ Notes       Automation consent granted

  






  
Install

  

    
      ❯git clone https://github.com/31Carlton7/mac-cli.git && cd mac-cli && make install
      
    
  

  

    
      ❯mac doctor
      
    
    
      
      View on GitHub