Khph - Simplified File Tagging

Khph is a tool for managing collections of files from the command line.  It allows you to tag files via links, and query your collection with a simple query language.

Khph is for when you just want to tag your recent trip's photos, without worrying about what all-in-one program to use, or how it stores its metadata.  With khph, the file system is the database.

Quick Start

Suppose ~/Pictures contains all of your photos, unorganized.  With some minor setup:

$ cd ~/Pictures
$ echo 'sourceDirs: [all]' >.khph
$ mkdir all
$ mv *.* all/

We can then start tagging photos: (using shell brace expansion)

$ khph --tag-create /people/{me,friends} /places/{home,beach}
$ khph --tag-add me --files DSCN0001.jpg DSCN0003.jpg --print-file-actions
ln -s ../../all/DSCN0001.jpg ~/Pictures/people/me/DSCN0001.jpg
ln -s ../../all/DSCN0003.jpg ~/Pictures/people/me/DSCN0003.jpg
$ khph --tag-add home --files DSCN{0001..0004}.jpg
$ khph --tag-add beach friends --files DSCN{0005..0007}.jpg
... and so on ...

After that, we can make various useful queries:

(Look at all photos of myself or my family:)
$ khph --list 'tag at "me" or at "family"' | xargs geeqie

(Create a tag containing photos of people at my home:)
$ khph --realize /results 'tag atbelow "people" and tag atbelow "home"'

(Recreate the tag to contain yet-untagged photos:)
$ khph --realize /results 'no tag'

(Delete the tag, we're done with it:)
$ rm -r results

The query syntax is flexible and is described in full in the readme.

Recent News

2018-02-09: Gentoo overlay now listed in Layman

2016-06-22: Gentoo ebuild and Nix expression updates

2016-06-10: Announcing khph

See all posts related to Khph.


Khph is on Hackage. There is also a Gentoo ebuild in my overlay, and a Nix expression in Nixpkgs.


Khph is hosted on GitLab: project page, issue tracker. Clone the source from one of:


Khph is free software.  It is licensed under the Affero General Public License (v3 or later).