# Overview
Gcardvault is a command-line utility which exports all of a user's Google Contacts in vCard/VCF format for backup (or portability).
Features:
- Automatically discovers all of a user's contacts
- Downloads them in vCard/VCF format and saves them to disk for archival
- Optionally manages version history for each contact 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](https://developers.google.com/identity/protocols/oauth2) to authenticate (via OAuth2/OIDC)
- Uses Google's [People API](https://developers.google.com/people/api/rest/) to discover a user's contacts
- Uses Google's [CardDAV endpoints](https://developers.google.com/people/carddav) to download vCard/VCF contacts
- Uses [GitPython](https://gitpython.readthedocs.io) to manage local git repo for version history under the covers
# Usage
Some example commands...
Sync all contacts for `foo.bar@gmail.com` user:
```
gcardvault sync foo.bar@gmail.com
```
Simply export contacts, do not save version history:
```
gcardvault sync foo.bar@gmail.com --export-only
```
See the [CLI help](https://github.com/rtomac/gcardvault/blob/main/src/USAGE.txt) for full usage and other notes.
# Requirements
- Python 3.9+
# Installation
## Via PyPi
```
pip install gcardvault
gcardvault sync foo.bar@gmail.com
```
## Via Docker
```
docker run -it --rm \
-v ${HOME}/.gcardvault:/root/.gcardvault \
-v ${PWD}/gcardvault:/root/gcardvault \
rtomac/gcardvault sync foo.bar@gmail.com
```
# 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 Gcardvault in its default configuration, you are initiating the OAuth2 flow with Google using Gcardvault'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 is recommended to create your own client ID through the [Google API Console](https://console.developers.google.com/), since the shared client ID may be used by others and subject to limits which may cause unpredictable failures.
[rclone](https://rclone.org) has a good write-up on [making your own client ID](https://rclone.org/drive/#making-your-own-client-id).
You can provide your client ID and secret to gcardvault as follows:
```
gcardvault sync foo.bar@gmail.com --client-id my_client_id --client-secret my_client_secret
```
# Development
Source repository:<br>
http://github.com/rtomac/gcardvault
## Install dependencies and run locally
```
pip install virtualenv
make devenv
. ./.devenv/bin/activate
gcardvault --help
```
## Run tests
```
pytest
```
## Build distribution
```
make dist
```
## Build Docker image
```
make docker-build
```
## Run via Docker image
```
make docker-run user=foo.bar@gmail.com
```
## Release to PyPi and Docker Hub
```
make release
```
See targets and variables in [Makefile](https://github.com/rtomac/gcardvault/blob/main/Makefile) for more options.
# License
MIT License
Raw data
{
"_id": null,
"home_page": "http://github.com/rtomac/gcardvault",
"name": "gcardvault",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "Google Contacts, gmail, contacts, backup, export, vCard, VCF, CardDav",
"author": "Ryan Tomac",
"author_email": "ryan@tomacfamily.com",
"download_url": "https://files.pythonhosted.org/packages/89/9f/d6a59be5081cab9587f61baf4692fbeca641a197727ec5eee09d66d5cf53/gcardvault-2.0.0.tar.gz",
"platform": null,
"description": "# Overview\n\nGcardvault is a command-line utility which exports all of a user's Google Contacts in vCard/VCF format for backup (or portability).\n\nFeatures:\n- Automatically discovers all of a user's contacts\n- Downloads them in vCard/VCF format and saves them to disk for archival\n- Optionally manages version history for each contact in an on-disk \"vault\" (a git repo under the covers)\n- Can be run via Docker image (multi-arch) or installed directly as a Python package with command-line interface\n\n# How it works\n\n- Uses Google's [Identity Provider](https://developers.google.com/identity/protocols/oauth2) to authenticate (via OAuth2/OIDC)\n- Uses Google's [People API](https://developers.google.com/people/api/rest/) to discover a user's contacts\n- Uses Google's [CardDAV endpoints](https://developers.google.com/people/carddav) to download vCard/VCF contacts\n- Uses [GitPython](https://gitpython.readthedocs.io) to manage local git repo for version history under the covers\n\n# Usage\n\nSome example commands...\n\nSync all contacts for `foo.bar@gmail.com` user:\n```\ngcardvault sync foo.bar@gmail.com\n```\n\nSimply export contacts, do not save version history:\n```\ngcardvault sync foo.bar@gmail.com --export-only\n```\n\nSee the [CLI help](https://github.com/rtomac/gcardvault/blob/main/src/USAGE.txt) for full usage and other notes.\n\n# Requirements\n\n- Python 3.9+\n\n# Installation\n\n## Via PyPi\n\n```\npip install gcardvault\ngcardvault sync foo.bar@gmail.com\n```\n\n## Via Docker\n\n```\ndocker run -it --rm \\\n -v ${HOME}/.gcardvault:/root/.gcardvault \\\n -v ${PWD}/gcardvault:/root/gcardvault \\\n rtomac/gcardvault sync foo.bar@gmail.com\n```\n\n# OAuth2 authentication\n\nThe CLI initiates an OAuth2 authentication the first time it is run (interactive), and then uses refresh tokens for subsequent runs (headless).\n\nWhen you use Gcardvault in its default configuration, you are initiating the OAuth2 flow with Google using Gcardvault'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.\n\nThat said, it is recommended to create your own client ID through the [Google API Console](https://console.developers.google.com/), since the shared client ID may be used by others and subject to limits which may cause unpredictable failures.\n\n[rclone](https://rclone.org) has a good write-up on [making your own client ID](https://rclone.org/drive/#making-your-own-client-id).\n\nYou can provide your client ID and secret to gcardvault as follows:\n```\ngcardvault sync foo.bar@gmail.com --client-id my_client_id --client-secret my_client_secret\n```\n\n# Development\n\nSource repository:<br>\nhttp://github.com/rtomac/gcardvault\n\n## Install dependencies and run locally\n```\npip install virtualenv\nmake devenv\n. ./.devenv/bin/activate\ngcardvault --help\n```\n\n## Run tests\n```\npytest\n```\n\n## Build distribution\n```\nmake dist\n```\n\n## Build Docker image\n```\nmake docker-build\n```\n\n## Run via Docker image\n```\nmake docker-run user=foo.bar@gmail.com\n```\n\n## Release to PyPi and Docker Hub\n```\nmake release\n```\n\nSee targets and variables in [Makefile](https://github.com/rtomac/gcardvault/blob/main/Makefile) for more options.\n\n# License\n\nMIT License\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Command-line utility which exports all of a user's Google Contacts in vCard/VCF format for backup (or portability)",
"version": "2.0.0",
"project_urls": {
"Homepage": "http://github.com/rtomac/gcardvault"
},
"split_keywords": [
"google contacts",
" gmail",
" contacts",
" backup",
" export",
" vcard",
" vcf",
" carddav"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "899fd6a59be5081cab9587f61baf4692fbeca641a197727ec5eee09d66d5cf53",
"md5": "0203cb897b19ac51035dd65a690986c5",
"sha256": "18d48610cfbcf78598c7ae941d93eb1f0dd3281ac8ad213cbfa8a49e17414b5b"
},
"downloads": -1,
"filename": "gcardvault-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "0203cb897b19ac51035dd65a690986c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 13960,
"upload_time": "2025-09-13T15:56:44",
"upload_time_iso_8601": "2025-09-13T15:56:44.781393Z",
"url": "https://files.pythonhosted.org/packages/89/9f/d6a59be5081cab9587f61baf4692fbeca641a197727ec5eee09d66d5cf53/gcardvault-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-13 15:56:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rtomac",
"github_project": "gcardvault",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gcardvault"
}
JSON
