KHARD.CONF(5)

📦
version 0.22.0 · 10 versions
, in arch rolling

💅 KHARD.CONF(5) — the khard config file, explained by your favorite Unix bestie 🎀

okay so this is the manual for khard.conf, the config file for khard. yes bestie, the whole page. grab a matcha, we're going in 🍓

✨ NAME ✨

khard.conf — the configuration file for khard, periodt.

🌸 SUMMARY 🌸

So the khard config file is literally just a plain text file with ini-like syntax. no cap. a bunch of the options even have a matching command line option, so you can vibe either way.

and here's the one thing you cannot skip: the only mandatory section in the whole file is the definition of the available address books. everything else? optional, babe 🫶

🦋 LOCATION 🦋

khard goes looking for the file at $XDG_CONFIG_HOME/khard/khard.conf. if $XDG_CONFIG_HOME is unset, it uses ~/.config/ in its stead. easy.

you can also move the whole thing around with the environment variable $KHARD_CONFIG or with the command line option -c — and heads up, -c takes precedence 👑

⭐ SYNTAX ⭐

the syntax is an ini-style dialect, and it gets parsed with the configobj library. the precise definition of the corresponding ini syntax lives at <https://configobj.readthedocs.io/en/latest/configobj.html#the-config-file-format> — go read it if you want the full tea ☕

it supports sections marked with square brackets, and nested sections with more square brackets. each section contains several keys with values delimited by equal signs. and the values are typed and type checked — so yes, it will absolutely call you out if you put nonsense in there 💀

✨ OPTIONS ✨

the config file consists of these four sections. four! iconic number, no notes:

📚 addressbooks

this section describes the addressbooks that are known to khard. it contains several subsections, but at least one.

each subsection can have an arbitrary title, must have a path key, and may have a type key. the optional type can be either discover or vdir (which is the default 💫).

  • a subsection with type vdir describes a single addressbook. in this case the title of the subsection is the name of the addressbook as it is referenced in khard.
  • with a type of discover, the subsection might describe several addressbooks which are discovered by globbing. the name of each addressbook will be the basename of the folder found via globbing.

the path key contains the path to the folder containing the vCard files for that addressbook. the path value supports environment variables and tilde prefixes 🏠. when using the discover type, it also supports globbing (for the exact syntax see :module:glob`` ).

and one lil requirement: khard expects the vCard files to hold only one VCARD record each and end in a .vcf extension. don't try to be cute and stuff multiple records in there 🙈

⚙️ general

this section lets you configure some general features about khard. the following keys are available in this section:

  • debug — a boolean indicating whether the logging level should be set to debug by default (same effect as the --debug option on the command line)
  • default_action — the default action/subcommand to use if the first non option argument does not match any of the available subcommands
  • editor — the text editor to use to edit address book entries; if not given, $EDITOR will be used
  • merge_editor — a command used to merge two cards interactively; if not given, $MERGE_EDITOR will be used

📋 contact table

this section is used to configure the behaviour of different output listings of khard. the following keys are available:

  • display — which part of the name to use in listings; this can be one of first_name, last_name or formatted_name
  • group_by_addressbook — whether or not to group contacts by address book in listings
  • localize_dates — whether to localize dates or to use ISO date formats
  • preferred_email_address_type — labels of email addresses to prefer
  • preferred_phone_number_type — labels of telephone numbers to prefer
  • reverse — whether to reverse the order of contact listings or not
  • show_nicknames — whether to show nick names
  • show_uids — whether to show uids
  • show_kinds — whether to show kinds
  • sort — field by which to sort contact listings

🪪 vcard

  • private_objects — a list of strings; these are the names of private vCard fields (starting with X-) that will be loaded and displayed by khard
  • search_in_source_files — whether to search in the vCard files before parsing them in order to speed up searches
  • skip_unparsable — whether to skip unparsable vCards; otherwise khard exits on the first unparsable card it encounters 😭
  • preferred_version — the preferred vCard version to use for new cards

🌈 EXAMPLE 🌈

this is the example config file — steal it, copy it, make it yours, it's giving starter pack 💖:

# 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

2020, Eric Scheibler — thank you for your service, king 🫶

and that's the whole page, bestie. this was khard.conf(5) from khard version 0.22, dated Oct 05, 2026. go forth and configure slayfully 💅✨

📦 where this page comes from