carddav-query - Man Page

Query a CardDAV server for contact names and emails.


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).


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


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


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


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


  carddav-source =
  carddav-source-cred-cmd = pass
  address-book-cmd = carddav-query -S fastmail %s


  carddav-source =
  carddav-source-cred-cmd = pass
  address-book-cmd = carddav-query -S gmail %s

See Also



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

Referenced By