📇 Cardamum

CLI to manage contacts

Table of contents

• Features
• Usage
  • List addressbooks
  • List vCards
  • Edit vCard
• Installation
• Configuration
  • Google
  • Apple
  • Microsoft
  • Posteo
• FAQ
• Sponsoring

Features

• CardDAV et Vdir support
• Native TLS support via native-tls crate (requires native-tls feature)
• Rust TLS support via rustls crate with:
  • AWS crypto support (requires rustls-aws feature)
  • Ring crypto support (requires rustls-ring feature)
• Shell command and keyring storages (requires command and keyring features)
• JSON support with --json

Cardamum CLI is written in Rust, and relies on cargo features to enable or disable functionalities. Default features can be found in the features section of the Cargo.toml, or on docs.rs.

Usage

List addressbooks

$ cardamum addressbooks list

| ID      | NAME                | DESC | COLOR |
|---------|---------------------|------|-------|
| default | default addressbook |      |       |

List vCards

$ cardamum card list default

| ID                                              | VERSION   | FN           | EMAIL                   | TEL             |
|-------------------------------------------------|-----------|--------------|-------------------------|-----------------|
| pimp_X3Xwu-58rVRwlbUeiptAUMyVK3HkJ45jJt3PjZaE7g | 3.0       | Forrest Gump | forrestgump@example.com | (404) 555-1212  |
| 62196d36-65cb-4a6b-b107-f3d8dc8d8b62            | 3.0       | Jean Dupont  | jean.dupont@example.com | +1234 56789     |

Edit vCard

$ cardamum card update default 62196d36-65cb-4a6b-b107-f3d8dc8d8b62

You text editor opens with the content of your vCard:

BEGIN:VCARD
VERSION:3.0
N:Gump;Forrest
FN:Forrest Gump
ORG:Bubba Gump Shrimp Co.
TITLE:Shrimp Man
PHOTO;VALUE=URL;TYPE=GIF:http://www.example.com/dir_photos/my_photo.gif
TEL;TYPE=WORK;VOICE:(111) 555-1212
TEL;TYPE=HOME;VOICE:(404) 555-1212
ADR;TYPE=WORK:;;100 Waters Edge;Baytown;LA;30314;United States of America
LABEL;TYPE=WORK:100 Waters Edge\nBaytown, LA 30314\nUnited States of America
ADR;TYPE=HOME:;;42 Plantation St.;Baytown;LA;30314;United States of America
LABEL;TYPE=HOME:42 Plantation St.\nBaytown, LA 30314\nUnited States of America
EMAIL;TYPE=PREF,INTERNET:forrestgump@example.com
REV:20080424T195243Z
END:VCARD

Once edition done, you should see the following message:

Card successfully updated

Installation

The project is still experimental, it has not been released yet.

Pre-built binary

Cardamum CLI can be installed with a pre-built binary. Find the latest releases GitHub workflow and look for the Artifacts section. You should find a pre-built binary matching your OS.

MacOS aarch64 and Windows i686 builds are broken, please use the next installation method until the first release.

Cargo (git)

Cardamum CLI can also be installed with cargo:

cargo install --locked --git https://github.com/pimalaya/cardamum.git

Configuration

The wizard is not yet available (it should come soon), so the only way to configure Cardamum CLI is to copy the sample config file, to store it either at ~/.config/cardamum.toml or ~/.cardamumrc then to customize it by commenting or uncommenting the options you need.

Google

Google Contacts requires OAuth 2.0. The first step is to configure an OAuth 2.0 token manager like Ortie:

carddav.auth.bearer.command = ["ortie", "token", "show"]
carddav.discover.host = "www.googleapis.com"
carddav.discover.method = "PROPFIND"

Discovery is the recommended way to go, but it is slow. If you want faster calls you can "hardcode" the server URI and/or the home URI, at your own risk:

carddav.server-uri = "https://www.googleapis.com/carddav/v1/principals"
carddav.home-uri = "https://www.googleapis.com/carddav/v1/principals/your.email@gmail.com/lists"

Apple

Apple Contacts does not propose discovery service, the only way is to use their server URI combined with basic authentication:

carddav.server-uri = "https://contacts.icloud.com"
carddav.auth.basic.username = "your.email@example.com"
carddav.auth.basic.password.raw = "p@$$w0rd"

If you check attentively the --trace logs, you should see the home URI. It is not recommended to use it directly, but it can make the CLI definitely faster. It should look like this:

carddav.home-uri = "https://p156-contacts.icloud.com:443/17170244959/carddavhome/"

Microsoft

Microsoft only proposes a proprietary, non-standard API.

Posteo

Posteo proposes a discovery service, combined with basic authentication:

carddav.discover.host = "posteo.de"
carddav.auth.basic.username = "your.email"
carddav.auth.basic.password.raw = "p@$$w0rd"

Discovery is the recommended way to go, but it is slow. If you want faster calls you can "hardcode" the server URI and/or the home URI, at your own risk:

carddav.server-uri = "https://posteo.de:8843"
carddav.home-uri = "https://posteo.de:8843/addressbooks/your.email/"

FAQ

Sponsoring

Special thanks to the NLnet foundation and the European Commission that helped the project to receive financial support from various programs:

• NGI Assure in 2022
• NGI Zero Entrust in 2023
• NGI Zero Core in 2024 (still ongoing)

If you appreciate the project, feel free to donate using one of the following providers: