docs/cli.md

   1 # QMK CLI
   2
   3 This page describes how to setup and use the QMK CLI.
   4
   5 # Overview
   6
   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.
   8
   9 * [Global CLI](#global-cli)
  10 * [Local CLI](#local-cli)
  11 * [CLI Commands](#cli-commands)
  12
  13 # Requirements
  14
  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).
  16
  17 # Global CLI
  18
  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.
  20
  21 ## Install Using Homebrew (macOS, some Linux)
  22
  23 If you have installed [Homebrew](https://brew.sh) you can tap and install QMK:
  24
  25 ```
  26 brew tap qmk/qmk
  27 brew 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
  30 ```
  31
  32 ## Install Using easy_install or pip
  33
  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:
  35
  36 ```
  37 pip3 install qmk
  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
  40 ```
  41
  42 ## Packaging For Other Operating Systems
  43
  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:
  45
  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`.
  50
  51 # Local CLI
  52
  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`.
  54
  55 **Example**:
  56
  57 ```
  58 $ ~/qmk_firmware/bin/qmk hello
  59 Ψ Hello, World!
  60 ```
  61
  62 ## Local CLI Limitations
  63
  64 There are some limitations to the local CLI compared to the global CLI:
  65
  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
  69
  70 # CLI Commands
  71
  72 ## `qmk cformat`
  73
  74 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.
  75
  76 **Usage**:
  77
  78 ```
  79 qmk cformat [file1] [file2] [...] [fileN]
  80 ```
  81
  82 ## `qmk compile`
  83
  84 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.
  85
  86 **Usage for Configurator Exports**:
  87
  88 ```
  89 qmk compile <configuratorExport.json>
  90 ```
  91
  92 **Usage for Keymaps**:
  93
  94 ```
  95 qmk compile -kb <keyboard_name> -km <keymap_name>
  96 ```
  97
  98 ## `qmk flash`
  99
 100 This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default.
 101 To specify a different bootloader, use `-bl <bootloader>`. Visit <https://docs.qmk.fm/#/flashing>
 102 for more details of the available bootloaders.
 103
 104 **Usage for Configurator Exports**:
 105
 106 ```
 107 qmk flash <configuratorExport.json> -bl <bootloader>
 108 ```
 109
 110 **Usage for Keymaps**:
 111
 112 ```
 113 qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader>
 114 ```
 115
 116 **Listing the Bootloaders**
 117
 118 ```
 119 qmk flash -b
 120 ```
 121
 122 ## `qmk config`
 123
 124 This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration.md).
 125
 126 **Usage**:
 127
 128 ```
 129 qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
 130 ```
 131
 132 ## `qmk docs`
 133
 134 This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
 135
 136 **Usage**:
 137
 138 ```
 139 qmk docs [-p PORT]
 140 ```
 141
 142 ## `qmk doctor`
 143
 144 This command examines your environment and alerts you to potential build or flash problems.
 145
 146 **Usage**:
 147
 148 ```
 149 qmk doctor
 150 ```
 151
 152 ## `qmk json-keymap`
 153
 154 Creates a keymap.c from a QMK Configurator export.
 155
 156 **Usage**:
 157
 158 ```
 159 qmk json-keymap [-o OUTPUT] filename
 160 ```
 161
 162 ## `qmk kle2json`
 163
 164 This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite.
 165
 166 **Usage**:
 167
 168 ```
 169 qmk kle2json [-f] <filename>
 170 ```
 171
 172 **Examples**:
 173
 174 ```
 175 $ qmk kle2json kle.txt
 176 ☒ File info.json already exists, use -f or --force to overwrite.
 177 ```
 178
 179 ```
 180 $ qmk kle2json -f kle.txt -f
 181 Ψ Wrote out to info.json
 182 ```
 183
 184 ## `qmk list-keyboards`
 185
 186 This command lists all the keyboards currently defined in `qmk_firmware`
 187
 188 **Usage**:
 189
 190 ```
 191 qmk list-keyboards
 192 ```
 193
 194 ## `qmk new-keymap`
 195
 196 This command creates a new keymap based on a keyboard's existing default keymap.
 197
 198 **Usage**:
 199
 200 ```
 201 qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
 202 ```
 203
 204 ## `qmk pyformat`
 205
 206 This command formats python code in `qmk_firmware`.
 207
 208 **Usage**:
 209
 210 ```
 211 qmk pyformat
 212 ```
 213
 214 ## `qmk pytest`
 215
 216 This command runs the python test suite. If you make changes to python code you should ensure this runs successfully.
 217
 218 **Usage**:
 219
 220 ```
 221 qmk pytest
 222 ```