iCloud for Omarchy
iCloud apps for Omarchy (and any Arch Linux), sharing
one Apple sign-in, published as one signed pacman repository.
Screenshots use demo data.
- Notes: your Apple Notes as a folder of Markdown files, synced both
ways. Edit, rename, move or delete them in the app, in Neovim or Obsidian,
or with
mv and rm, and iCloud follows.
- Photos: browse, download, upload and delete (with undo) your iCloud
Photos, copy one or make it your wallpaper.
- Find My: your devices on a map, with play sound, Lost Mode and a
location trail.
- Reminders: your lists and reminders, completed with a click, and a
desktop notification when one falls due, window open or not.
- Contacts: search your address book, copy a number or start an email
in a click, add and edit contacts, and export them as vCards.
- iCloud Drive:
~/iCloud Drive, a folder kept in sync both ways. No
app: use your file manager.
- Every window action also works from the terminal, with JSON output
for scripts and AI agents.
curl -fsSL https://github.com/ferdousbhai/icloud-for-omarchy/releases/latest/download/install.sh | sudo bash
| Directory | Package | What it is |
|---|
| notes/, notes-sync/ | icloud-notes | Apple Notes as a Qt/QML app and the icloud-notes command, synced with iCloud by its engine, icloud-notes-sync (notes-sync/, in Rust, originally derived from icloud-md), which the package installs off PATH. |
| photos/ | icloud-photos | iCloud Photos in GTK4/libadwaita: browse, download, upload and delete. |
| findmy/ | icloud-findmy | Find My devices in GTK4/libadwaita: locate, play a sound, Lost Mode, history trail. |
| reminders/ | icloud-reminders | iCloud Reminders in GTK4/libadwaita, and a systemd timer that notifies through Omarchy's notifications when a reminder falls due. |
| contacts/ | icloud-contacts | iCloud Contacts in GTK4/libadwaita: search, add, edit, delete, vCard export. |
| drive/ | icloud-drive | iCloud Drive as the folder ~/iCloud Drive, synced both ways by a background service; icloud-drive start turns it on. |
| session/, sessiond/ | icloud-session | The shared sign-in: a D-Bus daemon, a sign-in window and a CLI (sessiond/), plus the Rust client crate every app links (session/). |
The shared sign-in's design (the daemon, its D-Bus interface, the session
files) is in session/README.md.
Calendar, Mail and the rest of iCloud
Two more iCloud apps live in their own repositories, because they also
show other accounts in the same window. Both use this project's
icloud-session sign-in, so you don't sign in again:
- iCloud Calendar: Cloud Calendar
(
cloud-calendar account add icloud) shows your iCloud, Google and HEY
calendars together, with event notifications.
- iCloud Mail: Cloudmail
(
cloudmail account add icloud) reads, sends and searches iCloud Mail
next to your own domains' mail, HEY and Gmail.
Messages, Phone and Maps are not covered. iMessage and phone calls need an
Apple device: iCloud has no web service for them. Apple Maps' saved places
aren't available from iCloud on the web either.
Command line and agents
Notes, Photos, Find My, Reminders, Contacts, iCloud Drive and the shared sign-in have scriptable CLIs with one
output contract: text on a terminal, a JSON envelope when piped (--quiet
for the bare result), JSON errors with stable codes, and shared exit codes;
see docs/AGENTS.md and docs/CLI.md.
icloud-session skill install installs the agent skill
(docs/skills/icloud/SKILL.md) to ~/.agents/skills/icloud, linked
into ~/.claude/skills for Claude Code; icloud-session skill remove removes it, and a new
release refreshes it.
- docs/AGENTS.md: the reference to give an agent (auth,
commands with example JSON, safety rules, recipes).
- docs/skills/icloud/SKILL.md: the same as a
Claude Code skill; copy
docs/skills/icloud into ~/.claude/skills/.
- docs/CLI.md: every GUI feature mapped to its command, the
exit and error codes, the JSON shapes.
Signing in is the one thing a person must do: Apple's page (password, 2FA)
opens in a window from icloud-session sign-in.
Is this safe?
- You sign in on Apple's own page, password and two-factor code
included, in a window opened by
icloud-session sign-in. The apps never
see your password.
- What's kept is the session cookies, in your system keyring (the
Secret Service, e.g. GNOME Keyring). Only who is signed in and when the
session was last checked are in a file,
~/.local/state/icloud-session/account.json, readable only by you.
- Your password is stored only if you choose to, for Find My, which asks
for it again from time to time:
icloud-session set-password puts it in
your system keyring (the Secret Service, e.g. GNOME Keyring), and
icloud-session forget-password removes it.
- The apps talk only to Apple, plus OpenStreetMap for Find My's map
tiles.
- Notes and Photos deletes are recoverable: a note or photo you
delete goes to Recently Deleted in iCloud (about 30 days).
- Contacts deletes are not: iCloud has no Recently Deleted for
contacts, so the app and
icloud-contacts delete ask first. Only
icloud.com's Data Recovery (Restore Contacts, a whole earlier version of
your address book) brings one back.
- It's all open source, and the packages are signed with a key whose
fingerprint is pinned in install.sh.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
