CARDDAV-QUERY(1)            General Commands Manual           CARDDAV-QUERY(1)

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

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)

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

                                  2024-04-07                  CARDDAV-QUERY(1)