tCard

Edit and merge vCards as ergonomic TOML

tcard edit

full-name = "Jane Doe"
nickname = ["Janie"]
organization = ["Acme", "Engineering"]
title = "Engineer"
birthday = 1996-04-15

[[email]]
type = "work"
value = "jane@acme.example"

[[phone]]
type = "cell"
value = "+1-555-0100"

Output:

BEGIN:VCARD
VERSION:4.0
UID:urn:uuid:1f34e439-ca07-446f-af28-f5b7d3afcfc8
FN:Jane Doe
NICKNAME:Janie
ORG:Acme;Engineering
TITLE:Engineer
BDAY:19960415
EMAIL;TYPE=work:jane@acme.example
TEL;TYPE=cell:+1-555-0100
END:VCARD

This repository ships two interfaces: a Rust library projecting a card to TOML and folding the edits back, and a CLI printing, editing and merging cards through $EDITOR, or folding an already edited form back with apply.

Table of contents

• Features
• Installation
• Usage
• AI policy
• License
• Social
• Contributing
• Sponsoring

Features

• Ergonomic projection: a card becomes a fillable TOML form, its cryptic property names becoming readable keys.
• Structured names and addresses: N and ADR expand into named components, and a typed property lists the TYPE values it accepts.
• Discoverable properties: the blank form lists every property tCard knows, with empty values, so filling one needs no reference.
• Minimal, lossless diffs: only the lines you changed are re-rendered, and every other line keeps the card's own bytes.
• Verbatim passthrough: a property tCard does not list, a parameter the form hides and a group prefix all survive an edit untouched.
• Three-way merge: merge reconciles two divergent cards against their base, writing what it cannot decide as duplicate TOML keys.
• Interactive editing in $EDITOR, or in the command --editor names, behind the opt-in cli cargo feature.

Installation

Pre-built binary

As root:

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

As a regular user:

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

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

For a more up-to-date version, check the releases workflow and look for the Artifacts section: those are built from master, with the default cargo features.

Cargo

The binary lives behind the cli feature, which is off by default so that a library consumer pays for none of it:

cargo install --locked --features cli tcard

The library alone is a tcard dependency, which pulls in none of that:

cargo add tcard

Nix

If you have the Flakes feature enabled:

nix profile install github:pimalaya/tcard

Or run without installing:

nix run github:pimalaya/tcard -- template < contact.vcf

Sources

git clone https://github.com/pimalaya/tcard
cd tcard
nix run

Usage

Library

See documentation at docs.rs.

CLI

Run tcard --help for the full command tree, and tcard <command> --help for a command's arguments and what it does with them.

A source is a path to a vCard file, - for stdin, or literal vCard contents; omitting it starts from a blank form. A few real command lines:

tcard template
tcard template contact.vcf
tcard template - < contact.vcf
tcard edit contact.vcf
tcard edit - < contact.vcf > updated.vcf
tcard edit --output alice.vcf
tcard edit --version 3.0 --output bob.vcf
tcard edit --editor "code --wait" contact.vcf
tcard apply form.toml contact.vcf           # fold an edited form back, no editor
tcard template contact.vcf | edit-somehow | tcard apply - contact.vcf
tcard merge base.vcf local.vcf remote.vcf --output merged.vcf

The editor is the one --editor names, then $VISUAL, then $EDITOR, and nothing after those: tCard picks none of its own, and says so when neither variable is set. It reads no configuration file, so set them in your shell. The command is spawned on the path of a temporary TOML file it edits in place, so it must block until the edit is done: use code --wait, not code.

Logs go to stderr, so they can be redirected to a file while the command output stays on stdout:

tcard template contact.vcf --log-level debug 2>/tmp/tcard.log

Use --log-file <PATH> to append them to a file directly. When --log-level is omitted the RUST_LOG environment variable is consulted, and RUST_BACKTRACE=1 adds the full error backtrace.

License

This project is licensed under either of:

• MIT license
• Apache License, Version 2.0

Social

• Chat on Matrix
• News on Mastodon or RSS
• Mail at pimalaya.org@posteo.net

Sponsoring

Special thanks to the NLnet foundation and the European Commission that have been financially supporting the project for years:

• 2022 → 2023: NGI Assure
• 2023 → 2024: NGI Zero Entrust
• 2024 → 2026: NGI Zero Core
• 2026 → 2027: NGI Zero Commons Fund

This program is part of Pimalaya, free software funded entirely by grants and donations. If you find it useful, consider sponsoring its development: