☁️ icloud-cli-tools

Access your iCloud Calendar, Reminders, Notes, and Find My devices from the Linux terminal.

Features

• 📅 Calendar — List, create, and delete events with natural date parsing
• ✅ Reminders — Manage reminders across lists, mark complete, set priorities
• 📝 Notes — Read, create, and search your iCloud Notes
• 📍 Find My — Locate devices, play sounds, activate Lost Mode
• 🔄 Background Sync — Daemon with systemd integration for periodic caching
• 🔐 Secure Auth — 2FA support, OS keyring for credentials, session caching
• 🎨 Beautiful Output — Rich tables, JSON, and plain text formats

Installation

# From PyPI (recommended)
pip install icloud-cli-tools

Or install from source:

# Clone the repo
git clone https://github.com/alan13367/icloud-cli-tools.git
cd icloud-cli-tools

# Set up a virtual environment (recommended, required on modern Debian/Ubuntu)
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Tip: To use icloud-cli without activating the venv every time, add an alias:

echo 'alias icloud-cli="~/icloud-cli-tools/.venv/bin/icloud-cli"' >> ~/.bashrc
source ~/.bashrc

Quick Start

# 1. Login to your iCloud account
icloud-cli login

# 2. Set up Notes access (requires app-specific password)
icloud-cli notes setup-imap

# 3. Start using it!
icloud-cli calendar list
icloud-cli reminders list
icloud-cli notes list
icloud-cli findmy list

Usage

Authentication

icloud-cli login          # Interactive login with 2FA
icloud-cli logout         # Clear all stored credentials
icloud-cli status         # Check auth status

Calendar

icloud-cli calendar list                    # Events for next 7 days
icloud-cli calendar list --from today --to tomorrow
icloud-cli calendar show <event-id>
icloud-cli calendar add -t "Meeting" -s "2025-06-15 10:00" -e "2025-06-15 11:00"
icloud-cli calendar delete <event-id>

Reminders

icloud-cli reminders list                   # All active reminders
icloud-cli reminders list --list "Shopping" --completed
icloud-cli reminders add -t "Buy milk" -d "2025-06-15" -l "Shopping"   # bare date -> all-day reminder
icloud-cli reminders add -t "Standup" -d "2025-06-15 09:30"            # date + time -> timed reminder
icloud-cli reminders complete <reminder-id>
icloud-cli reminders delete <reminder-id>

Notes

icloud-cli notes list
icloud-cli notes show <note-id>
icloud-cli notes add -t "My Note" -b "Note content here"
icloud-cli notes search "keyword"

Note: Notes access requires an app-specific password. Generate one at appleid.apple.com → Sign In & Security → App-Specific Passwords.

Find My

icloud-cli findmy list                      # All devices with status
icloud-cli findmy locate "iPhone"           # GPS coordinates + Maps link
icloud-cli findmy play-sound "iPhone"       # Ring your device
icloud-cli findmy lost-mode "iPhone" -p "+1234567890" -m "Please return"

Sync & Daemon

icloud-cli sync                # One-shot sync to local cache
icloud-cli daemon start        # Start background sync (every 15 min)
icloud-cli daemon stop         # Stop daemon
icloud-cli daemon status       # Check daemon status

Systemd Integration (Linux)

# Install the service
cp systemd/icloud-cli-sync.service ~/.config/systemd/user/
systemctl --user enable icloud-cli-sync
systemctl --user start icloud-cli-sync

Output Formats

icloud-cli calendar list -f table   # Rich formatted table (default)
icloud-cli calendar list -f json    # Machine-readable JSON
icloud-cli calendar list -f plain   # Tab-separated for scripting

Configuration

Config file: ~/.config/icloud-cli/config.toml

[general]
default_format = "table"
verbose = false

[auth]
apple_id = "your@icloud.com"

[sync]
sync_interval_minutes = 15

[calendar]
default_calendar = "Personal"

[reminders]
default_reminder_list = "Reminders"

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check src/ tests/

⚠️ Disclaimer

This project uses unofficial/private iCloud web APIs via the pyicloud library. Apple may change these APIs at any time without notice, which could break functionality. This tool is not affiliated with or endorsed by Apple Inc.

License

MIT