---
name: "carddav-query"
section: "1"
platform: "linux"
package: "aerc"
version: "0.22.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/carddav-query"
---

# carddav-query(1)

Query a CardDAV server for contact names and emails.

## NAME

carddav-query - Query a CardDAV server for contact names and emails.

## 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\>* ...\]

This tool has been tailored for use as **address-book-cmd** in [**aerc-config**(5)](/aerc-config/5.md).

## OPTIONS

- **-h**, **--help**

  show this help message and exit

- **-v**, **--verbose**

  Print debug info on stderr.

- **-l** *\<limit\>*, **--limit** *\<limit\>*

  Maximum number of results returned by the server. If the server does not support limiting, this option will be disregarded.

  Default: *10*

- **-c** *\<file\>*, **--config-file** *\<file\>*

  INI configuration file from which to read the CardDAV URL endpoint.

  Default: *~/.config/aerc/accounts.conf*

- **-S** *\<section\>*, **--config-section** *\<section\>*

  INI configuration section where to find *\<key\_source\>* and *\<key\_cred\_cmd\>*. By default the first section where *\<key\_source\>* is found will be used.

- **-k** *\<key\_source\>*, **--config-key-source** *\<key\_source\>*

  INI configuration key to lookup in *\<section\>* from *\<file\>*. The value must respect the following format:

  https?://*\<username\>*\[:*\<password\>*\]@*\<hostname\>*/*\<path/to/addressbook\>*

  Both *\<username\>* and *\<password\>* must be percent encoded. 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\>*

  INI configuration key to lookup in *\<section\>* from *\<file\>*. The value is a command that will be executed with **sh -c** to determine *\<password\>* if it is not present in *\<key\_source\>*.

  Default: *carddav-source-cred-cmd*

- **-s** *\<server\_url\>*, **--server-url** *\<server\_url\>*

  CardDAV server URL endpoint. Overrides configuration file.

- **-u** *\<username\>*, **--username** *\<username\>*

  Username to authenticate on the server. Overrides configuration file.

- **-p** *\<password\>*, **--password** *\<password\>*

  Password for the specified user. Overrides configuration file.

## POSITIONAL ARGUMENTS

*\<term\>*

Search term. Will be used to search contacts from their FN (formatted name), EMAIL, NICKNAME, ORG (company) and TITLE fields.

## EXAMPLES

These are excerpts of *~/.config/aerc/accounts.conf*.

### 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

[**aerc-config**(5)](/aerc-config/5.md)

## AUTHORS

Originally created by Drew DeVault and maintained by Robin Jarry who is assisted by other open source contributors. For more information about aerc development, see *https://sr.ht/~rjarry/aerc/*.