# Garmin Health Data Sync - Automated Scheduling Guide

## Daily Automatic Sync with Cron

To automatically sync your Garmin health data every day, you can set up a cron job on your macOS system.

### Option 1: User Crontab (Recommended)

1. **Open crontab editor:**
   ```bash
   crontab -e
   ```

2. **Add the following line** (adjust time and path as needed):
   ```bash
   # Sync Garmin health data every day at 8:00 AM
   0 8 * * * cd /Users/lili/workspace/bulter && /Users/lili/workspace/bulter/venv/bin/python /Users/lili/workspace/bulter/scripts/daily_sync.py >> /Users/lili/workspace/bulter/logs/cron.log 2>&1
   ```

3. **Save and exit** (in vi: press `Esc`, then type `:wq` and press Enter)

### Option 2: launchd (macOS Native)

Create a LaunchAgent plist file for more reliable macOS scheduling:

1. **Create plist file:**
   ```bash
   nano ~/Library/LaunchAgents/com.butler.garmin.sync.plist
   ```

2. **Add the following content:**
   ```xml
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
       <key>Label</key>
       <string>com.butler.garmin.sync</string>

       <key>ProgramArguments</key>
       <array>
           <string>/Users/lili/workspace/bulter/venv/bin/python</string>
           <string>/Users/lili/workspace/bulter/scripts/daily_sync.py</string>
       </array>

       <key>WorkingDirectory</key>
       <string>/Users/lili/workspace/bulter</string>

       <key>StartCalendarInterval</key>
       <dict>
           <key>Hour</key>
           <integer>8</integer>
           <key>Minute</key>
           <integer>0</integer>
       </dict>

       <key>StandardOutPath</key>
       <string>/Users/lili/workspace/bulter/logs/launchd.log</string>

       <key>StandardErrorPath</key>
       <string>/Users/lili/workspace/bulter/logs/launchd-error.log</string>

       <key>RunAtLoad</key>
       <false/>
   </dict>
   </plist>
   ```

3. **Load the LaunchAgent:**
   ```bash
   launchctl load ~/Library/LaunchAgents/com.butler.garmin.sync.plist
   ```

4. **Start the agent:**
   ```bash
   launchctl start com.butler.garmin.sync
   ```

5. **Verify it's loaded:**
   ```bash
   launchctl list | grep garmin
   ```

### Managing the LaunchAgent

**Unload (stop):**
```bash
launchctl unload ~/Library/LaunchAgents/com.butler.garmin.sync.plist
```

**Reload (after editing):**
```bash
launchctl unload ~/Library/LaunchAgents/com.butler.garmin.sync.plist
launchctl load ~/Library/LaunchAgents/com.butler.garmin.sync.plist
```

**Test manually:**
```bash
launchctl start com.butler.garmin.sync
```

### Cron Syntax Reference

```
* * * * * command
│ │ │ │ │
│ │ │ │ └─── Day of week (0-7, 0 and 7 are Sunday)
│ │ │ └───── Month (1-12)
│ │ └─────── Day of month (1-31)
│ └───────── Hour (0-23)
└─────────── Minute (0-59)
```

**Examples:**
- Every day at 8:00 AM: `0 8 * * *`
- Every day at 10:30 PM: `30 22 * * *`
- Twice a day (8 AM and 8 PM): `0 8,20 * * *`
- Every 6 hours: `0 */6 * * *`

### Logs

Sync logs are written to:
- Main sync log: `/Users/lili/workspace/bulter/logs/daily_sync.log`
- Cron output: `/Users/lili/workspace/bulter/logs/cron.log`
- LaunchAgent output: `/Users/lili/workspace/bulter/logs/launchd.log`

**View recent sync logs:**
```bash
tail -f /Users/lili/workspace/bulter/logs/daily_sync.log
```

**Check cron execution:**
```bash
tail -f /Users/lili/workspace/bulter/logs/cron.log
```

### Troubleshooting

**Cron job not running:**
1. Check cron is enabled on macOS:
   ```bash
   sudo launchctl list | grep cron
   ```

2. Grant Full Disk Access to cron:
   - System Preferences → Security & Privacy → Privacy tab
   - Select "Full Disk Access"
   - Add `/usr/sbin/cron`

3. Check logs for errors

**LaunchAgent not working:**
1. Check if it's loaded:
   ```bash
   launchctl list | grep garmin
   ```

2. Check logs:
   ```bash
   cat ~/Library/LaunchAgents/com.butler.garmin.sync.plist
   tail /Users/lili/workspace/bulter/logs/launchd-error.log
   ```

3. Verify permissions:
   ```bash
   ls -la ~/Library/LaunchAgents/com.butler.garmin.sync.plist
   ```

**Authentication errors:**
- Ensure `.env` file has correct credentials
- Check token store permissions: `~/.garmin/tokens`

### Manual Sync

You can always manually trigger a sync:
```bash
cd /Users/lili/workspace/bulter
source venv/bin/activate
python scripts/daily_sync.py
```

Or using the CLI:
```bash
python -m health.cli.sync sync-incremental
```

### Best Practices

1. **Choose optimal sync time:** Early morning (e.g., 8 AM) ensures previous day's data is available
2. **Monitor logs regularly:** Check for authentication or API errors
3. **Test before scheduling:** Run manual sync to ensure everything works
4. **Backup data periodically:** The `data/health/` directory contains all synced data