📇 Cardamum

CLI to manage contacts

Table of contents

• Features
• Usage
  • List addressbooks
  • List cards
  • Edit card
• Installation
• Configuration
  • Google
  • Apple
  • Microsoft
  • Posteo
• FAQ
• Sponsoring

Features

• CardDAV and 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 cards

$ cardamum card list default

| ID                                              | VERSION   | FN           | EMAIL                   | TEL             |
|-------------------------------------------------|-----------|--------------|-------------------------|-----------------|
| pimp_X3Xwu-58rVRwlbUeiptAUMyVK3HkJ45jJt3PjZaE7g | 3.0       | Forrest Gump | [email protected] | (404) 555-1212  |
| 62196d36-65cb-4a6b-b107-f3d8dc8d8b62            | 3.0       | Jean Dupont  | [email protected] | +1234 56789     |

Edit card

$ 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:[email protected]
REV:20080424T195243Z
END:VCARD

Once edition done, you should see the following message:

Card successfully updated

Installation

Pre-built binary

Cardamum CLI can be installed with the installer:

As root:

curl -sSL https://raw.githubusercontent.com/pimalaya/cardamum/master/install.sh | sudo sh

As a regular user:

curl -sSL https://raw.githubusercontent.com/pimalaya/cardamum/master/install.sh | PREFIX=~/.local sh

These commands install the latest binary from the GitHub releases section.

If you want a more up-to-date version than the latest release, check out the releases GitHub workflow and look for the Artifacts section. You should find a pre-built binary matching your OS. These pre-built binaries are built from the master branch, using default features.

Cargo

Cardamum CLI can be installed with cargo:

cargo install cardamum

With only Vdir support:

cargo install cardamum --no-default-features --features vdir

You can also use the git repository for a more up-to-date (but less stable) version:

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

Nix

Cardamum CLI can be installed with Nix:

nix-env -i cardamum

You can also use the git repository for a more up-to-date (but less stable) version:

nix-env -if https://github.com/pimalaya/cardamum/archive/master.tar.gz

Or, from within the source tree checkout:

nix-env -if .

If you have the Flakes feature enabled:

nix profile install cardamum

Or, from within the source tree checkout:

nix profile install

You can also run Cardamum directly without installing it:

nix run cardamum

Configuration

The wizard is not yet available (it should come soon, see #7), 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/[email protected]/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 = "[email protected]"
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: