Zach White

A practical programmer with 2 decades of experience.

I will solve your business needs by crafting tools suited to your level of scale.

My Company

My Software

© 2021 Zach White.
All rights reserved.

QMK CLI

QMK CLI is a Python tool that makes using QMK easier. It is also used extensively in our build process as part of the Data Driven QMK initiative.

History

When I introduced info.json files to QMK Firmware the only software that consumed them was the QMK API. This made it difficult for keyboard maintainers to create correct info.json files without running QMK API locally. As we started to develop Data Driven QMK it became obvious that we’d need a CLI to address this and other problems that were starting to crop up as QMK’s popularity grew.

I made the decision to use Python for this purpose primarily because the expertise was already there and we had a lot of code already written for QMK API. We looked at writing this using JavaScript, but the JS ecosystem was extremely unstable at the time. We had already been bitten by this problem with our QMK Flasher tool. We also examined golang for this purpose which had a lot of promise and was very fast, but we felt it would be easier to find community contributors if it were in Python instead.

Design

The QMK CLI follows the subcommand pattern. Like git the first argument to the qmk command designates the action you wish to take. Some common commands that users run are qmk setup, qmk info, and qmk compile.

The core of QMK CLI contains only a handful of commands- qmk config, qmk clone, and qmk setup. These allow a user to bootstrap their environment. At startup time qmk will attempt to locate a qmk_firmware checkout, and if found it will add ${QMK_HOME}/qmk_firmware/lib/python to sys.path and import additional commands as well. At this time we provide over 40 subcommands between the QMK CLI and QMK Firmware.

While the time involved in importing and registering so many commands is not trivial, the benefits to both development time and the richness of the user experience this enables makes the startup overhead worthwhile. Even on a slow machine this overhead is typically less than 1 second, and can be as low as 100 ms.

OS Packages

Most users use pip to install the QMK CLI. We are in the process of creating OS specific packages that use virtualenv to deploy a complete application without conflict with system modules. I have personally created packages for the following OS’s:

Evolution

Initially the QMK CLI started with only a few commands. Over time many more were added. I personally wrote or extensively improved upon many of the commands that users and our build system use today:

I also have helped others to design and craft their vision. Some of the command I have helped shepherd through the PR process include: