khard 0.12.0 documentation

# Welcome to khard’s documentation!

Khard is an address book for the Linux command line. It can read, create, modify and delete carddav 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 Linux 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 the Development section below.

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

A minimal configuration is provided in the source tree. It looks like this:

    # example configuration file for khard version >= 0.13.0
    # place it under $HOME/.config/khard/khard.conf

    [addressbooks]
    [[family]]
    path = ~/.contacts/family/
    [[friends]]
    path = ~/.contacts/friends/

    [general]
    debug = no
    default_action = list
    editor = vim
    merge_editor = vimdiff

    [contact table]
    # display names by first or last name: first_name / last_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
    # sort by first or last name: first_name / last_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
    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

## Integration with other programs

Khard can be used together with email or SIP clients or a synchronisation program like vdirsyncer.

### mutt

Khard may be used as an external address book for the email client mutt. To accomplish that, add the following to your mutt config file (mostly `~/.mutt/muttrc`):

    set query_command= "khard email --parsable %s"
    bind editor <Tab> complete-query
    bind editor ^T    complete

Then you can complete email addresses by pressing the Tab-key in mutt’s new mail dialog. If your address books contain hundreds or even thousands of contacts and the query process is very slow, you may try the `--search-in-source-files` option to speed up the search:

    set query_command= "khard email --parsable --search-in-source-files %s"

If you want to complete multi-word search strings like “john smith” then you may try out the following instead:

    set query_command = "echo %s | xargs khard email --parsable --"

To add email addresses to khard’s address book, you may also add the following lines to your muttrc file:

    macro index,pager A \
      "<pipe-message>khard add-email<return>" \
      "add the sender email address to khard"

Then navigate to an email message in mutt’s index view and press “A” to start the address import dialog.

### Alot

Add the following lines to your alot config file:

    [accounts]
        [[youraccount]]
            [[[abook]]]
                type = shellcommand
                command = khard email --parsable
                regexp = '^(?P<email>[^@]+@[^\t]+)\t+(?P<name>[^\t]+)'
                ignorecase = True

### Twinkle

For those who also use the SIP client twinkle to take phone calls, khard can be used to query incoming numbers. The plugin tries to find the incoming caller id and speaks it together with the phone’s ring tone. The plugin needs the following programs:

    sudo aptitude install ffmpeg espeak sox mpc

sox and ffmpeg are used to cut and convert the new ring tone and espeak speaks the caller id. mpc is a client for the music player daemon (mpd). It’s required to stop music during an incoming call. Skip the last, if you don’t use mpd. Don’t forget to set the “stop_music”-parameter in the `config.py` file to `False`, too.

After the installation, copy the scripts and sounds folders to your twinkle config folder:

    cp -R misc/twinkle/* ~/.twinkle/

Then edit your twinkle config file (mostly `~/.twinkle/twinkle.cfg`) like this:

    # RING TONES
    # We need a default ring tone. Otherwise the phone would not ring at all, if
    # something with the custom ring tone creation goes wrong.
    ringtone_file=/home/USERNAME/.twinkle/sounds/incoming_call.wav
    ringback_file=/home/USERNAME/.twinkle/sounds/outgoing_call.wav

    # SCRIPTS
    script_incoming_call=/home/USERNAME/.twinkle/scripts/incoming_call.py
    script_in_call_answered=
    script_in_call_failed=/home/USERNAME/.twinkle/scripts/incoming_call_failed.py
    script_outgoing_call=
    script_out_call_answered=
    script_out_call_failed=
    script_local_release=/home/USERNAME/.twinkle/scripts/incoming_call_ended.py
    script_remote_release=/home/USERNAME/.twinkle/scripts/incoming_call_ended.py

### Zsh

The file `misc/zsh/_khard` contains a khard cli completion function for the zsh and `misc/zsh/_email-khard` completes email addresses.

Install by copying to a directory where zsh searches for completion functions (the `$fpath` array). If you, for example, put all completion functions into the folder `~/.zsh/completions` you must add the following to your zsh main config file:

    fpath=( $HOME/.zsh/completions $fpath )
    autoload -U compinit
    compinit

### sdiff

Use the wrapper script `misc/sdiff/sdiff_khard_wrapper.sh` if you want to use sdiff as your contact merging tool. Just make the script executable and set it as your merge editor in khard’s config file:

    merge_editor = /path/to/sdiff_khard_wrapper.sh

# Development

Khard is developed on Github where you are welcome to post bug reports, feature requests or join the discussion in general.

The develop branch is used for active development so please open all pull requests for new features against that branch. Only bug fixes should be opened against master.

In order to start coding you need to fetch the develop branch:

    git clone https://github.com/scheibler/khard
    cd khard
    git fetch --all
    git checkout develop
    pip3 install --editable .

Alternatively you can use the `setup.py` script directly. If you want to isolate khard from your system Python environment you can use a virtualenv to do so.

# Indices and tables

- Index

- Module Index

- Search Page