# 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