Created : Wed Aug 24 22:41:42 IST 2011

This is only a short introduction and some key points of interest. For more details on how to use ASynK please refer to the included documentation, or the official website for ASynK is at: http://asynk.io/ You will find links to latest download, complete documentation, and other information on that website.

ASynK - Awesome Sync (by Karra), is a flexible Contacts synchronization platform written in Python. High level features include:

• ASynK allows two-way sync of Contacts across any two supported sources - Google Contacts, Microsoft Exchange Online, iCloud Contacts, any CardDAV server and Emacs BBDB.
• You can use ASynK to copy contacts from one Google account to another (say from a Google Apps account at work to a personal address before you leave your job). You can do this at the level of folders (see below)
• ASynK is the only two-way synchronization option for BBDB known to be in existence today. So if you are keen to keep your BBDB content synchronized with a mobile device or Outlook, look no further.
• ASynK works on Windows, MacOS X, and Linux. Outlook synchronization only works on Windows
• Synchronization is granular to the level of ‘Folders’, i.e. you can synchronize one folder of Google Contacts with an Exchange folder, and another Google folder in the same account with BBDB
• The infrastructure is there to add more database and item types (i.e. tasks, notes, etc.), but currently only Contacts synchronization is supported.
• It is free software, and released under the GNU AGPL (Affero GPL) version 3

As you are reading this file, the most efficient installation is to clone this git repository to your machine. Then see the section titled Usage below to invoke ASynK.

git clone  https://github.com/skarra/ASynK.git

ASynK is written in Python 3. For the best experience you will need Python 3.10 or later. There are many python packages dependencies that are captured in requirements.txt file. We recommend creating a separate virtualenv for keeping all the dependencies up to date.

$ cd ASynK
$ python3.10 -m venv venv
$ source venv/bin/activate
$ pip install -r requirements.txt
$ python asynk.py --version # sanity test to make sure basic dependencies are in order

The setup requriements vary depending on which contact database you want to use.

• The BBDB and Outlook PST connectors are entirely local so there is no authentication required at all to access these stores.
• CardDAV: You need end user credentials for the accoounts you want to access on the CardDAV server. CardDAV uses HTTP Basic authentication with a server URL, username, and password. ASynK supports any standard CardDAV server (Radicale, Baikal, Nextcloud, etc.).
• iCloud Contacts: iCloud exposes contacts via CardDAV at contacts.icloud.com. You need your Apple ID email and an app-specific password (not your regular Apple ID password). Generate one at https://appleid.apple.com/account/manage under “App-Specific Passwords”.

  ASynK can securely cache your iCloud password in the OS-native credential store (macOS Keychain, GNOME Keyring, or Windows Credential Locker) via the keyring Python package. During initial setup (asynk.py init) you will be offered to save the password. On subsequent sync runs the password is retrieved automatically — no prompting required. You can override the cached value at any time with --icpwd.

• Google Contacts:
  • Google Contacts uses oAuth, and this requires two types of credentails: a Client credential and a user credential.
  • Google Contacts uses the People API v1 with OAuth 2.0. ASynK ships with default shared credentials so you can get started immediately — a browser window will open during setup for you to sign in and authorize access

    Note: The default credentials are shared among all ASynK users. If you encounter rate-limit errors, you should register your own Google Cloud project and use your own client secrets. See doc/google_app_registration.md for detailed step-by-step instructions.

  • On first run ASynK will open a browser to initiate an oauth authorization flow for a user account. ASynK will automatically trigger the required web flows to get the user consent and acquire oauth tokens.
• MS Exchange Server:
  • This also uses oAuth, and the general principle is the same as for Google Contacts.
  • Exchange Online uses the Microsoft Graph API with OAuth 2.0 device code flow. ASynK ships with a default shared app registration so you can get started immediately.

    Note: The default app registration is shared among all ASynK users. If you encounter rate-limit errors, you should register your own app in Microsoft Entra ID (formerly Azure Active Directory). See doc/azure_app_registration.md for detailed step-by-step instructions.

  • On first run ASynK will open a browser to initiate an oauth authorization flow for a user account. ASynK will automatically trigger the required web flows to get the user consent and acquire oauth tokens.

ASynK comes with an interactive set up wizard to help get you up and running. This is the recommended way to start as a first time user, or if an dwhen you want to add more sync profiles.

$ python asynk.py init

For further usage help, try “python asynk.py –help”. You can also read the docs for more detailed information about underlying concepts and reference to all the features.