NAME

       mcds — mutt CardDAV query

SYNOPSIS

       mcds [-c config_file] [-hVvp] [-q a | e | n | t] [-S] [-s a | e | n | t] [-u URL] term

DESCRIPTION

       The  mcds utility queries a CardDAV server for requested information.  Its primary function is to provide
       an address query command for mutt(1).

       The options are as follows:

       -c config_file
               Specifies an alternative configuration file. The default file is ~/.mcdsrc.

       -h      Print help text to standard output and exit.

       -p      Prompt for a password.

       -q a | e | n | t
               The term to query against.  Known terms are:

               a       Query for the address field.

               e       Query for the email field.  This is the default.

               n       Query for the full-name field.

               t       Query for the telephone field.

       -S      Save the password.

       -s a | e | n | t
               The search term to return.  Known terms are:

               a       Query for the address field.

               e       Query for the email field.  This is the default.

               n       Query for the full-name field.

               t       Query for the telephone field.

       -u URL  The URL of the CardDAV server.

       -V      Print the version number and license information of mcds to standard output and exit.

       -v      Enable verbose mode.  Forces mcds to print debugging messages about its progress.

FILES

       ~/.mcdsrc
               Configuration file.  Used to set default values for mcds, but can be overridden with command-line
               arguments.  Formatted as a list of “key = value” pairs separated by newlines.

               The keys are as follows:

               url = URL
                       The URL of the CardDAV server.

               verify = [yes | no]
                       Verify server certificate if connecting over HTTPS.  Disabled by default.

               netrc = [yes | no]
                       Enable reading the ~/.netrc file.  Disabled by default.

               username = USERNAME
                       The username to login to the CardDAV server with.  If a username is specified  mcds  will
                       not use the ~/.netrc file.

               password_file = password.gpg
                       The GPG encrypted file containing the password for the CardDAV server.

               libsecret = [yes | no]
                       Use library “libsecret” to store and retrieve the password.

       ~/.netrc
               Used  to  access  your  username and password when authenticating with the CardDAV server, if you
               have not specified your username and password file in ~/.mcdsrc.

EXIT STATUS

       The mcds utility exits 0 on success, and >0 if an error occurs.

EXAMPLES

       Query a CardDAV server for email addresses corresponding to “Ben”:

             $ mcds -u https://localhost/caldav.php/username/addressbook/ Ben
             ben@example.net        Ben Smith
             ...

       To use mcds with mutt, add the following to your muttrc(5):

             set query_command="mcds -u https://localhost/caldav.php/username/addressbook/ '%s'"

       This query can be simplified by putting the relevant values in ~/.mcdsrc:

             url = https://localhost/caldav.php/username/addressbook/
             verify = no
             netrc = yes

       Now the query command can be shortened to:

             set query_command="mcds '%s'"

       When compiled against and after enabling libsecret in the configuration file,  mcds  can  save  passwords
       provided at the password prompt. To set, replace or clear the password, run

             mcds -pS

SEE ALSO

       curl(1), gpg2(1), mutt(1), muttrc(5), netrc(5)

AUTHORS

       The mcds utility is maintained by Timothy Brown <tbrown@freeshell.org>

Debian                                          November 5, 2024                                         MCDS(1)