ZMK Studio CLI

At the time of publication, this code is not officially part of the ZMK project, and is primarily made to be a debug tool for trying out the Studio RPC protocol

This is sample code that leverages the ZMK RPC Protocol to interact with keyboards with ZMK Studio enabled.

Precompiled versions of the Protobuf files from zmk-studio-messages have been included for convenience.

Setup

1. Install Python
2. Clone a copy of this repository and navigate to its root directory
3. Run pip install -e ".[dev]"

Usage

Currently, only USB transport is available. After installing ZMK Studio CLI, you may invoke commands in the following format:

zmk-studio-cli [OPTIONS] <subsystem> <command>

Options

Option	Description
-p, --port	Serial port to use with USB transport. [required]
-v, --version	Print version and exit.
--install-completion	Install completion for the current shell
--show-completion	Show completion for the current shell, to copy it or customize the installation
--help	Show help message and exit.

Subsystems

Subsystem	Description
core	Get system information and state
behaviors	Get stored behavior information
keymap	Get/set keymap data

Core

Command	Description
get-device-info	Get keyboard name and serial number
get-lock-state	Get ZMK Studio lock state
lock	Set ZMK Studio lock state, Currently always returns error RPC_NOT_FOUND
reset-settings	Reset ZMK Studio settings

Behaviors

Command	Description	Required Parameters
list-all-behaviors	List all behaviors stored on the keyboard by their IDs
get-behavior-details	Get a behavior's name and metadata from its ID	Behavior ID

Keymaps

Command	Description	Required Parameters	Optional Parameters
get-keymap	Print the keymap
set-layer-binding	Set a keybind on a specifc layer to the chosen behavior	Layer ID, Key Position, Behavior ID	Param1, Param2
check-unsaved-changes	Check for unsaved keymap changes
save-changes	Save keymap changes
discard-changes	Discard keymap changes
get-physical-layouts	Print all physical layouts
set-active-physical-layout	Set the active physical layout
move-layer	Move a layer from a start index to a destination index	Start Index, Destination Index
add-layer	Add a layer to the keymap
remove-layer	Remove a layer from the keymap at a chosen layer index	Layer Index
restore-layer	Restore a layer with the chosen layer ID to the keymap at the specified layer index	Layer ID, Layer Index
set-layer-props	Set layer properties at a specific layer ID	Layer ID, Layer Name

References

1. https://protobuf.dev/programming-guides/proto3/
2. https://protobuf.dev/getting-started/pythontutorial/
3. https://zmk.dev/docs/features/studio
4. https://github.com/zmkfirmware/zmk-cli