diff options
Diffstat (limited to 'docs/cli.md')
| -rw-r--r-- | docs/cli.md | 250 |
1 files changed, 250 insertions, 0 deletions
diff --git a/docs/cli.md b/docs/cli.md index 760fe1cdb..625ac4fb7 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -37,3 +37,253 @@ We are looking for people to create and maintain a `qmk` package for more operat * Document why in a comment when you do deviate * Install using a virtualenv * Instruct the user to set the environment variable `QMK_HOME` to have the firmware source checked out somewhere other than `~/qmk_firmware`. + +# Local CLI + +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`. + +**Example**: + +``` +$ ~/qmk_firmware/bin/qmk hello +Ψ Hello, World! +``` + +## Local CLI Limitations + +There are some limitations to the local CLI compared to the global CLI: + +* The local CLI does not support `qmk setup` or `qmk clone` +* The local CLI always operates on the same `qmk_firmware` tree, even if you have multiple repositories cloned. +* The local CLI does not run in a virtualenv, so it's possible that dependencies will conflict + +# CLI Commands + +## `qmk cformat` + +*dev mode* + +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. + +**Usage**: + +``` +qmk cformat [file1] [file2] [...] [fileN] +``` + +## `qmk compile` + +This command allows you to compile firmware from any directory. You can compile JSON exports from <https://config.qmk.fm>, compile keymaps in the repo, or compile the keyboard in the current working directory. + +**Usage for Configurator Exports**: + +``` +qmk compile <configuratorExport.json> +``` + +**Usage for Keymaps**: + +``` +qmk compile -kb <keyboard_name> -km <keymap_name> +``` + +**Usage in Keyboard Directory**: + +Must be in keyboard directory with a default keymap, or in keymap directory for keyboard, or supply one with `--keymap <keymap_name>` +``` +qmk compile +``` + +**Example**: +``` +$ qmk config compile.keymap=default +$ cd ~/qmk_firmware/keyboards/planck/rev6 +$ qmk compile +Ψ Compiling keymap with make planck/rev6:default +... +``` +or with optional keymap argument + +``` +$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4 +$ qmk compile -km 66_iso +Ψ Compiling keymap with make clueboard/66/rev4:66_iso +... +``` +or in keymap directory + +``` +$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak +$ qmk compile +Ψ Compiling keymap with make make gh60/satan:colemak +... +``` + +**Usage in Layout Directory**: + +Must be under `qmk_firmware/layouts/`, and in a keymap folder. +``` +qmk compile -kb <keyboard_name> +``` + +**Example**: +``` +$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi +$ qmk compile -kb dz60 +Ψ Compiling keymap with make dz60:mechmerlin-ansi +... +``` + +## `qmk flash` + +This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default. +To specify a different bootloader, use `-bl <bootloader>`. Visit <https://docs.qmk.fm/#/flashing> +for more details of the available bootloaders. + +**Usage for Configurator Exports**: + +``` +qmk flash <configuratorExport.json> -bl <bootloader> +``` + +**Usage for Keymaps**: + +``` +qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader> +``` + +**Listing the Bootloaders** + +``` +qmk flash -b +``` + +## `qmk config` + +This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration.md). + +**Usage**: + +``` +qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] +``` + +## `qmk docs` + +This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936. + +**Usage**: + +``` +qmk docs [-p PORT] +``` + +## `qmk doctor` + +This command examines your environment and alerts you to potential build or flash problems. It can fix many of them if you want it to. + +**Usage**: + +``` +qmk doctor [-y] [-n] +``` + +**Examples**: + +Check your environment for problems and prompt to fix them: + + qmk doctor + +Check your environment and automatically fix any problems found: + + qmk doctor -y + +Check your environment and report problems only: + + qmk doctor -n + +## `qmk json-keymap` + +Creates a keymap.c from a QMK Configurator export. + +**Usage**: + +``` +qmk json-keymap [-o OUTPUT] filename +``` + +## `qmk kle2json` + +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. + +**Usage**: + +``` +qmk kle2json [-f] <filename> +``` + +**Examples**: + +``` +$ qmk kle2json kle.txt +☒ File info.json already exists, use -f or --force to overwrite. +``` + +``` +$ qmk kle2json -f kle.txt -f +Ψ Wrote out to info.json +``` + +## `qmk list-keyboards` + +This command lists all the keyboards currently defined in `qmk_firmware` + +**Usage**: + +``` +qmk list-keyboards +``` + +## `qmk list-keymaps` + +This command lists all the keymaps for a specified keyboard (and revision). + +**Usage**: + +``` +qmk list-keymaps -kb planck/ez +``` + +## `qmk new-keymap` + +This command creates a new keymap based on a keyboard's existing default keymap. + +**Usage**: + +``` +qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] +``` + +## `qmk pyformat` + +*dev mode* + +This command formats python code in `qmk_firmware`. + +**Usage**: + +``` +qmk pyformat +``` + +## `qmk pytest` + +*dev mode* + +This command runs the python test suite. If you make changes to python code you should ensure this runs successfully. + +**Usage**: + +``` +qmk pytest +``` |