kpsh 1.0

Kpsh is a shell-like password manager, which bases on KeePass database format. Recently I have released its new version: 1.0.0. It can be installed from a PyPI. Source code is available on git.

There are 3 ways to use kpsh: as interactive shell, as a single shot command and as a daemon which can be accessed by client programs via a Unix socket.

This is the first “stable” version of kpsh (i.e. the one which doesn’t start from “0”) and I’m pretty excited about it. Kpsh turned 2 earlier this year, which took me by the surprise, because I have always felt that it’s still a pretty new project.

Another surprise it that I still find it enjoyable to code it after these 2 years. I guess that its initial architecture works for me - a thing which I can’t say about all of my projects. That’s why CHANGELOG for 1.0.0 is pretty impressive.

Here are some highlights.

Database editing

This release is a huge milestone because it finally implements manipulating (editing) of databases. You can add new entries, edit existing ones and delete them. Moving (renaming) entries is not supported yet - mainly because I forgot about it (read to the bottom of this release note to learn more about it).

It was challanging to design the interface of these commands. Usually KeePass clients are fully interactive GUI programs and users can visually inspect each element (like generated passwords) before changes are committed to the database. I resigned from the interactivity because it would cripple daemon mode. I understand though that human errors are real problem, so in the future Kpsh releases I plan to add ways to recover from them.

Another challange was to detect changes to database and prevent the loss of precious user input. For now kpsh doesn’t do merges (like e.g. KeePassXC), but it plays safe: it creates a new database with requested changes. Kpsh automatically switches to this new database, so any further modifications are saved to the new file.

Of course, it simply reloads the database when it’s safe (when there’s no user input yet).


I decided to stop using pipenv for dependency management and switched to Poetry instead. It wasn’t quick or pleasant change though; contrary to the opinions of, apparently, the whole internet, nothing had worked out of the box. In fact, I encountered critical bugs in either Poetry or its dependencies which were preventing ANY work at all.

What is more, stable release of Poetry doesn’t support distributing shell scripts, like setuptools. and Python Package Metadata Format do. It was a dealbreaker because kpsh ships the whole contrib1 section this way and it took some time before I discovered that this feature had been added in Poetry 1.2.0a.

It took me 2 days to debug Poetry, which I really didn’t want to do. I’m stubborn, though, and once the bugs were fixed and workarounds were found… wow. It was worth it. Poetry is great. Once again I can develop and run the tests quickly and easily.

Thanks to this, new and old kpsh code received nearly 100 new tests.

By the way, switching to Poetry doesn’t sound like this, but it is a breaking change because it changes the way in which kpsh can be installed from the git checkout directory.

Quality of life changes

There are some quality of life changes as well. Among them are:

  • better printing of entries by show command;
  • removing a socket when kpsh daemon exits;
  • creating new databases when kpsh is started with an unexisting path.

Future plans

What’s next? I hope to release next version still this month, but I want Kpsh to have implemented entries moving/renaming first. Which probably isn’t very big, but suddenly Warbreaker started eating all of my evenings. Good news is that books finally end. Bad news is that Brandon Sanderson is extremely fruitful author. :)

By the way, an important security feature (credentials checking for daemon mode) is already sitting on master, so you might want to upgrade Kpsh before the official release if it’s important for you.

  1. scripts which don’t belong to the core kpsh, but are for example a reference implementation of kpsh client.