CARDDAV-QUERY(1)

📦
version 0.22.0 · 14 versions
, in arch rolling

💅 CARDDAV-QUERY 💅

okay bestie, so this is carddav-query straight out of the General Commands Manual, and it's literally the little tool that lets you yell at a CardDAV server until it hands over contact names and emails. yes, it's that girl. 🎀

✨ NAME ✨

carddav-query — query a CardDAV server for contact names and emails. no cap, that's the whole job. 💖

🦋 SYNOPSIS 🦋

carddav-query [-h] [-l <limit>] [-v] [-c <file>] [-s <section>] [-k
<key_source>] [-C <key_cred_cmd>] [-s <server_url>] [-u <username>] [-p
<password>] <term> [<term> ...]

and like, quick lore drop: this tool has been tailored for use as address-book-cmd in aerc-config(5). she was built for that gig. 👑

🔥 OPTIONS 🔥

  • -h, --help — shows this help message and dips. classic.
  • -v, --verbose — prints debug info on stderr. so if you're like "why is this being weird 😭" this is your girl.
  • -l <limit>, --limit <limit> — the max number of results the server will return. and like, if the server doesn't support limiting, this option just gets disregarded. not her fault. 💅 Default: 10.
  • -c <file>, --config-file <file> — the INI configuration file she reads the CardDAV URL endpoint from. Default: ~/.config/aerc/accounts.conf.
  • -S <section>, --config-section <section> — tells her which INI configuration section to find <key_source> and <key_cred_cmd> in. if you don't say, she'll use the first section where <key_source> is found. she's resourceful like that. 🧚
  • -k <key_source>, --config-key-source <key_source> — the INI configuration key to look up in <section> from <file>. and the value must respect the following format, no exceptions bestie:
https?://<username>[:<password>]@<hostname>/<path/to/addressbook>

both <username> and <password> must be percent encoded, okay? and if <password> is omitted, it can be provided via --config-key-cred-cmd or --password. Default: carddav-source.

  • -C <key_cred_cmd>, --config-key-cred-cmd <key_cred_cmd> — another INI configuration key to look up in <section> from <file>. the value is a command that gets executed with sh -c to determine <password> if it's not present in <key_source>. sneaky but valid. ✨ Default: carddav-source-cred-cmd.
  • -s <server_url>, --server-url <server_url> — CardDAV server URL endpoint. overrides the configuration file. she said "I'll take it from here." 🌸
  • -u <username>, --username <username> — username to authenticate on the server. overrides the configuration file.
  • -p <password>, --password <password> — password for the specified user. overrides the configuration file.

🌈 POSITIONAL ARGUMENTS 🌈

  • <term> — your search term 🫶. it's used to search contacts from their FN (formatted name), EMAIL, NICKNAME, ORG (company) and TITLE fields. so yeah, she's checking five whole fields for you. iconic.

💀 EXAMPLES 💀

these are excerpts of ~/.config/aerc/accounts.conf. real snippets, real slay. ⭐

📧 Fastmail

[fastmail]
carddav-source = https://janedoe%40fastmail.com@carddav.fastmail.com/dav/addressbooks/user/janedoe@fastmail.com/Default
carddav-source-cred-cmd = pass fastmail.com/janedoe
address-book-cmd = carddav-query -S fastmail %s

📬 Gmail

[gmail]
carddav-source = https://johndoe%40gmail.com@www.googleapis.com/carddav/v1/principals/johndoe@gmail.com/lists/default
carddav-source-cred-cmd = pass gmail.com/johndoe
address-book-cmd = carddav-query -S gmail %s

👀 SEE ALSO 👀

💖 AUTHORS 💖

originally created by Drew DeVault and maintained by Robin Jarry, who is assisted by other open source contributors — a whole squad, fr fr. for more information about aerc development, see https://sr.ht/~rjarry/aerc/. 🫶

okay that's the whole page, go query some contacts bestie 💅

written up on 2026-09-07 — that's the date on this one, and the source/version line at the bottom says CARDDAV-QUERY(1) all over again, so like… full circle. 🦋✨

📦 where this page comes from