gcalvault 1.2.1

Command-line utility which exports all of a user's Google Calendars to iCal/ICS format for backup (or portability)

Overview

Gcalvault is a command-line utility which exports all of a user's Google Calendars to iCal/ICS format for backup (or portability).

Features:

• Automatically discovers all calendars visible the user
• Downloads them in iCal/ICS format and saves them to disk for archival
• Optionally manages version history for each calendar in an on-disk "vault" (a git repo under the covers)
• Can be run via Docker image (multi-arch) or installed directly as a Python package with command-line interface

How it works

• Uses Google's Identity Provider to authenticate (via OAuth2/OIDC)
• Uses Google's Calendar API to discover a user's calendars
• Uses Google's CalDav endpoints to download iCal/ICS calendars
• Uses GitPython to manage local git repo for version history under the covers

Usage

Some example commands...

Sync all calendars for [e-mail] user:

gcalvault sync [e-mail]

Sync one specific calendar:

gcalvault sync [e-mail] [e-mail]

Sync only "writable" calendars:

gcalvault sync [e-mail] --ignore-role reader

Simply export calendars, do not save version history:

gcalvault sync [e-mail] --export-only

See the CLI help for full usage and other notes.

Installation

Via Docker

docker run -it --rm \
    -v ${HOME}/.gcalvault:/root/.gcalvault \
    -v ${PWD}:/root/gcalvault \
    rtomac/gcalvault sync [e-mail]

Via PyPi

pip install gcalvault
gcalvault sync [e-mail]

OAuth2 authentication

The CLI initiates an OAuth2 authentication the first time it is run (interactive), and then uses refresh tokens for subsequent runs (headless).

When you use Gcalvault in its default configuration, you are authenticating with Google using Gcalvault's client ID. There is nothing inherently insecure about this, since the application is running locally and therefore only you will have access to the data it reads from Google.

That said, it's strongly recommended to create your own client ID through the Google API Console, since the shared client ID will be used by others and subject to limits which may cause unpredictable failures.

rclone has a good write-up on making your own client ID.

You can provide your client ID and secret to gcalvault as follows:

gcalvault sync [e-mail] --client-id my_client_id --client-secret my_client_secret

Development

Source repository:
http://github.com/rtomac/gcalvault

Install dependencies locally (for IDE)

make devenv
. ./.devenv/bin/activate

Build distribution and Docker image

make build

Build and test locally

make test

Build and run locally

make run user=[e-mail]

Release to PyPi and Docker Hub

make release

See targets and variables in Makefile for more options.

License

MIT License