Welcome to khard’s documentation!
*********************************

* Welcome to khard’s documentation!

* Command line usage

* Scripting

* Integration

* Contributing

* Man pages

* Indices and tables

* API Reference

Khard is an address book for the Unix command line.  It can read,
create, modify and delete vCard address book entries.  Khard only
works with a local store of vCard files.  It is intended to be used in
conjunction with other programs like an email client, text editor,
vdir synchronizer or VOIP client.


Installation
============

Khard is available as a native package for some *nix distributions so
you should check your package manager first.  If you want or need to
install manually you can use the release from PyPi:

   pip3 install khard

If you want to help the development or need more advanced installation
instructions see Contributing.

If you need a tarball use the one from PyPi and not from the Github
release page.  These are missing an auto generated python file.


Configuration
=============

The configuration file of khard is stored in the XDG conform config
directory. If the environment variable "$XDG_CONFIG_HOME" is set, it
is "$XDG_CONFIG_HOME/khard/khard.conf" and it defaults to
"~/.config/khard/khard.conf" otherwise.

An "example configuration" is provided in the source tree.  It looks
like this:

   # example configuration file for khard version > 0.14.0
   # place it under ~/.config/khard/khard.conf
   # This file is parsed by the configobj library.  The syntax is described at
   # https://configobj.readthedocs.io/en/latest/configobj.html#the-config-file-format

   [addressbooks]
   [[family]]
   path = ~/.contacts/family/
   [[friends]]
   path = ~/.contacts/friends/
   [[work]]
   path = ~/.work/**/client-*-contacts/
   type = discover

   [general]
   debug = no
   default_action = list
   # These are either strings or comma seperated lists
   editor = vim, -i, NONE
   merge_editor = vimdiff

   [contact table]
   # display names by first or last name: first_name / last_name / formatted_name
   display = first_name
   # group by address book: yes / no
   group_by_addressbook = no
   # reverse table ordering: yes / no
   reverse = no
   # append nicknames to name column: yes / no
   show_nicknames = no
   # show uid table column: yes / no
   show_uids = yes
   # show kind table column: yes / no
   show_kinds = no
   # sort by first or last name: first_name / last_name / formatted_name
   sort = last_name
   # localize dates: yes / no
   localize_dates = yes
   # set a comma separated list of preferred phone number types in descending priority
   # or nothing for non-filtered alphabetical order
   preferred_phone_number_type = pref, cell, home
   # set a comma separated list of preferred email address types in descending priority
   # or nothing for non-filtered alphabetical order
   preferred_email_address_type = pref, work, home

   [vcard]
   # extend contacts with your own private objects
   # these objects are stored with a leading "X-" before the object name in the vcard files
   # every object label may only contain letters, digits and the - character
   # example:
   #   private_objects = Jabber, Skype, Twitter
   # default: ,  (the empty list)
   private_objects = Jabber, Skype, Twitter
   # preferred vcard version: 3.0 / 4.0
   preferred_version = 3.0
   # Look into source vcf files to speed up search queries: yes / no
   search_in_source_files = no
   # skip unparsable vcard files: yes / no
   skip_unparsable = no

