.\" Generated by scdoc 1.11.3
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "CARDDAV-QUERY" "1" "2024-07-30"
.PP
.SH NAME
.PP
carddav-query - Query a CardDAV server for contact names and emails.\&
.PP
.SH SYNOPSIS
.PP
\fBcarddav-query\fR [\fB-h\fR] [\fB-l\fR \fI<limit>\fR] [\fB-v\fR] [\fB-c\fR \fI<file>\fR]
[\fB-s\fR \fI<section>\fR] [\fB-k\fR \fI<key_source>\fR] [\fB-C\fR \fI<key_cred_cmd>\fR]
[\fB-s\fR \fI<server_url>\fR] [\fB-u\fR \fI<username>\fR] [\fB-p\fR \fI<password>\fR] \fI<term>\fR [\fI<term>\fR .\&.\&.\&]
.PP
This tool has been tailored for use as \fBaddress-book-cmd\fR in \fBaerc-config\fR(5).\&
.PP
.SH OPTIONS
.PP
\fB-h\fR, \fB--help\fR
.RS 4
show this help message and exit
.PP
.RE
\fB-v\fR, \fB--verbose\fR
.RS 4
Print debug info on stderr.\&
.PP
.RE
\fB-l\fR \fI<limit>\fR, \fB--limit\fR \fI<limit>\fR
.RS 4
Maximum number of results returned by the server.\& If the server does not
support limiting, this option will be disregarded.\&
.PP
Default: \fI10\fR
.PP
.RE
\fB-c\fR \fI<file>\fR, \fB--config-file\fR \fI<file>\fR
.RS 4
INI configuration file from which to read the CardDAV URL endpoint.\&
.PP
Default: \fI~/.\&config/aerc/accounts.\&conf\fR
.PP
.RE
\fB-S\fR \fI<section>\fR, \fB--config-section\fR \fI<section>\fR
.RS 4
INI configuration section where to find \fI<key_source>\fR and
\fI<key_cred_cmd>\fR.\& By default the first section where \fI<key_source>\fR
is found will be used.\&
.PP
.RE
\fB-k\fR \fI<key_source>\fR, \fB--config-key-source\fR \fI<key_source>\fR
.RS 4
INI configuration key to lookup in \fI<section>\fR from \fI<file>\fR.\& The value
must respect the following format:
.PP
.RS 4
https?\&://\fI<username>\fR[:\fI<password>\fR]@\fI<hostname>\fR/\fI<path/to/addressbook>\fR
.PP
.RE
Both \fI<username>\fR and \fI<password>\fR must be percent encoded.\& If
\fI<password>\fR is omitted, it can be provided via \fB--config-key-cred-cmd\fR
or \fB--password\fR.\&
.PP
Default: \fIcarddav-source\fR
.PP
.RE
\fB-C\fR \fI<key_cred_cmd>\fR, \fB--config-key-cred-cmd\fR \fI<key_cred_cmd>\fR
.RS 4
INI configuration key to lookup in \fI<section>\fR from \fI<file>\fR.\& The value
is a command that will be executed with \fBsh -c\fR to determine
\fI<password>\fR if it is not present in \fI<key_source>\fR.\&
.PP
Default: \fIcarddav-source-cred-cmd\fR
.PP
.RE
\fB-s\fR \fI<server_url>\fR, \fB--server-url\fR \fI<server_url>\fR
.RS 4
CardDAV server URL endpoint.\& Overrides configuration file.\&
.PP
.RE
\fB-u\fR \fI<username>\fR, \fB--username\fR \fI<username>\fR
.RS 4
Username to authenticate on the server.\& Overrides configuration file.\&
.PP
.RE
\fB-p\fR \fI<password>\fR, \fB--password\fR \fI<password>\fR
.RS 4
Password for the specified user.\& Overrides configuration file.\&
.PP
.RE
.SH POSITIONAL ARGUMENTS
.PP
\fI<term>\fR
.RS 4
Search term.\& Will be used to search contacts from their FN (formatted
name), EMAIL, NICKNAME, ORG (company) and TITLE fields.\&
.PP
.RE
.SH EXAMPLES
.PP
These are excerpts of \fI~/.\&config/aerc/accounts.\&conf\fR.\&
.PP
.SS Fastmail
.PP
.nf
.RS 4
[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
.fi
.RE
.PP
.SS Gmail
.PP
.nf
.RS 4
[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
.fi
.RE
.PP
.SH SEE ALSO
.PP
\fBaerc-config\fR(5)
.PP
.SH AUTHORS
.PP
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 \fIhttps://sr.\&ht/~rjarry/aerc/\fR.\&