configure

Configure Apple PIM Access

Apple PIM is the Personal Information Manager plugin for Calendar, Reminders, Contacts, and Mail.

Help the user configure which domains, calendars, and reminder lists the apple-pim plugin can access.

Tip: If you encounter permission errors during configuration, use /apple-pim:authorize to check and request macOS permissions first.

Configuration Location

The config file is at ~/.config/apple-pim/config.json (JSON format). The Swift CLIs read this file directly via the PIMConfig library. Do NOT write to any plugin cache directory or use YAML/markdown format.

Process

1. Check permissions with apple-pim action config_show to see current config and action status for macOS access
   • If any domain shows notDetermined, use action authorize to trigger prompts
   • If any domain shows denied, warn the user and guide to System Settings
2. Discover available items with apple-pim action config_init — this lists ALL calendars and reminder lists from macOS
3. Read existing config from ~/.config/apple-pim/config.json if it exists
4. Ask which domains to enable (Calendars, Reminders, Contacts, Mail) — multi-select
5. For enabled domains with filtering (Calendars, Reminders):
   • Use the discovery data from apple-pim action config_init (do NOT use calendar action list — that returns filtered results)
   • Ask user which to allow
6. Set defaults for new events/reminders
7. Write config file as JSON to ~/.config/apple-pim/config.json
8. Confirm changes are effective immediately (no restart needed)

Configuration File Format

Write the config file as JSON to ~/.config/apple-pim/config.json:

{
  "calendars": {
    "enabled": true,
    "mode": "allowlist",
    "items": ["Calendar Name 1", "Calendar Name 2"]
  },
  "reminders": {
    "enabled": true,
    "mode": "allowlist",
    "items": ["List Name 1", "List Name 2"]
  },
  "contacts": {
    "enabled": true,
    "mode": "all",
    "items": []
  },
  "mail": {
    "enabled": true
  },
  "default_calendar": "Calendar Name",
  "default_reminder_list": "List Name"
}