Donate
mysticalsInstall guide
Pick an app and your system. About five minutes from download to your first synced calendar.
Download the .dmg for your chip
Apple menu → About This Mac. “Chip: Apple M…” →
Go to downloadsarm64. “Processor: Intel…” →x64.Drag Mysticals into Applications
Open the .dmg, drag the icon onto the Applications folder, then eject the disk image.
Add your first account
Add calendar → Google (you sign in in the browser) or CalDAV (pick a preset below). Give it a label and a colour. Repeat for every account, and each one gets its own box.
That’s it. Updates are automatic
The app downloads new releases for your architecture and updates itself.
Run the installer
Mysticals is shared unsigned, so SmartScreen warns about an unknown publisher. Click More info → Run anyway, then follow the installer. It asks whether to install just for you or for everyone on this computer (that one needs admin rights) and lets you pick the folder.
Add your first account
Add calendar → Google (you sign in in the browser) or CalDAV (pick a preset below). Give it a label and a colour. Repeat for every account, and each one gets its own box. Credentials are sealed with Windows DPAPI for your user.
Updates
When a new release is out, the status bar offers it. Click it to open the release page and run the new setup .exe over the old one.
Download the AppImage or .deb
Intel / AMD PCs take
Go to downloadsMysticals-x86_64.AppImage, ARM machines (Raspberry Pi 4 and 5, ARM laptops) takeMysticals-arm64.AppImage.uname -mtells you which:x86_64oraarch64. The AppImage runs on most distros, and on Debian or Ubuntu you can take the.debinstead.Install or run it
chmod +x Mysticals-x86_64.AppImage && ./Mysticals-x86_64.AppImage# orsudo apt install ./Mysticals-amd64.deb# on ARM: Mysticals-arm64.AppImage / Mysticals-arm64.debMake sure a keyring is running
Credentials are encrypted with the Secret Service (GNOME Keyring, KWallet). GNOME and KDE desktops have one already. Without one, Mysticals refuses to store credentials rather than keep them in plain text.
Add your first account
Add calendar → Google (you sign in in the browser) or CalDAV (pick a preset below). Repeat for every account. New releases show up in the status bar and open the release page.
Check Node.js 20.3+
No Node yet? Install it from nodejs.org, Homebrew (
brew install node), winget (winget install OpenJS.NodeJS.LTS), your distro or your version manager.node -v # v20.3.0 or newerInstall from npm
npm i -g mysticalsRun it
Press
?for keys. Want a look first? Mock mode gives you two fake isolated accounts and touches nothing real.mysticalsMYSTICALS_MOCK=1 mysticals # macOS, Linux$env:MYSTICALS_MOCK=1; mysticals # Windows PowerShellset "MYSTICALS_MOCK=1" && mysticals # Windows cmdAllow the Keychain item
On first use macOS asks to access the
mysticals-terminalKeychain item. Choose Always Allow: it holds the key that encrypts your credentials.Nothing to allow
The key that encrypts your credentials is sealed with Windows DPAPI for your user, in
master.keyin the data folder. Use Windows Terminal for the best mouse and colour support.Have a keyring and secret-tool
The key that encrypts your credentials goes into the Secret Service (GNOME Keyring, KWallet) through
secret-tool. Notifications usenotify-send.sudo apt install libsecret-tools # Fedora/Arch: libsecretAdd accounts with s
Press
s→ add Google or CalDAV. To update later, runnpm i -g mysticalsagain. The status line tells you when.
Keys
Mouse works too: click to select, click again to open, the wheel scrolls.
mysticals-terminal in ~/Library/Application Support (macOS), %APPDATA% (Windows) or ~/.local/share (Linux)Credentials are encrypted per account. The desktop and terminal apps never share data.Connect your calendars
Same steps in both apps. For CalDAV, use an app password. You need one when 2FA is on, and it’s a good idea anyway.
dav.privateemail.com/dav.php/App password from Private Email webmailcaldav.icloud.comApp-specific password from appleid.apple.comcaldav.fastmail.comSettings → Privacy & Security → App passwordsUsername is your full email address. Presets fill in the server URL for you.
Troubleshooting
libsecret-tools for the terminal app).daemon.log in the data folder. Stuck? Close every window, then pkill -f 'cli.js --daemon' (Windows: end the Node.js process in Task Manager).mouse on to pass clicks through.