3 This page describes how to setup and use the QMK CLI.
7 The QMK CLI makes building and working with QMK keyboards easier. We have provided a number of commands to simplify and streamline tasks such as obtaining and compiling the QMK firmware, creating keymaps, and more.
9 * [Global CLI](#global-cli)
10 * [Local CLI](#local-cli)
11 * [CLI Commands](#cli-commands)
15 The CLI requires Python 3.5 or greater. We try to keep the number of requirements small but you will also need to install the packages listed in [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt).
19 QMK provides an installable CLI that can be used to setup your QMK build environment, work with QMK, and which makes working with multiple copies of `qmk_firmware` easier. We recommend installing and updating this periodically.
21 ## Install Using Homebrew (macOS, some Linux)
23 If you have installed [Homebrew](https://brew.sh) you can tap and install QMK:
28 export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
29 qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment
32 ## Install Using easy_install or pip
34 If your system is not listed above you can install QMK manually. First ensure that you have python 3.5 (or later) installed and have installed pip. Then install QMK with this command:
38 export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
39 qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment
42 ## Packaging For Other Operating Systems
44 We are looking for people to create and maintain a `qmk` package for more operating systems. If you would like to create a package for your OS please follow these guidelines:
46 * Follow best practices for your OS when they conflict with these guidelines
47 * Document why in a comment when you do deviate
48 * Install using a virtualenv
49 * Instruct the user to set the environment variable `QMK_HOME` to have the firmware source checked out somewhere other than `~/qmk_firmware`.
53 If you do not want to use the global CLI there is a local CLI bundled with `qmk_firmware`. You can find it in `qmk_firmware/bin/qmk`. You can run the `qmk` command from any directory and it will always operate on that copy of `qmk_firmware`.
58 $ ~/qmk_firmware/bin/qmk hello
62 ## Local CLI Limitations
64 There are some limitations to the local CLI compared to the global CLI:
66 * The local CLI does not support `qmk setup` or `qmk clone`
67 * The local CLI always operates on the same `qmk_firmware` tree, even if you have multiple repositories cloned.
68 * The local CLI does not run in a virtualenv, so it's possible that dependencies will conflict
74 This command allows you to compile firmware from any directory. You can compile JSON exports from <https://config.qmk.fm> or compile keymaps in the repo.
76 **Usage for Configurator Exports**:
79 qmk compile <configuratorExport.json>
82 **Usage for Keymaps**:
85 qmk compile -kb <keyboard_name> -km <keymap_name>
90 This command formats C code using clang-format. Run it with no arguments to format all core code, or pass filenames on the command line to run it on specific files.
95 qmk cformat [file1] [file2] [...] [fileN]
100 This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration.md).
105 qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
110 This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
120 This command examines your environment and alerts you to potential build or flash problems.
128 ## `qmk list-keyboards`
130 This command lists all the keyboards currently defined in `qmk_firmware`
140 This command creates a new keymap based on a keyboard's existing default keymap.
145 qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
150 This command formats python code in `qmk_firmware`.
160 This command runs the python test suite. If you make changes to python code you should ensure this runs successfully.