~ruther/qmk_firmware

5cfc3ce02e3c8007ac42e8089ecc895771bb3bfb — Erovia 5 years ago 724f20e 
Rebase on master, hide some other subcommands

The list of hidden subcommands were approved by @skullydazed ;)
Currently hidden if 'user.developer' is not True:

  - cformat
  - docs
  - kle2json
  - pyformat
  - pytest
patch browse .tar.gz 
7 files changed, 25 insertions(+), 255 deletions(-)

M bin/qmk
M docs/cli.md
M docs/cli_commands.md
M docs/cli_development.md
M lib/python/qmk/cli/cformat.py
M lib/python/qmk/cli/docs.py
M lib/python/qmk/cli/kle2json.py

M bin/qmk => bin/qmk +1 -1
@@ 24,7 24,7 @@ def _check_modules(requirements):
        for line in fd.readlines():
            line = line.strip().replace('<', '=').replace('>', '=')

            if len(line) == 0 or line[0] == '#' or '-r' in line:
            if len(line) == 0 or line[0] == '#' or line.startswith('-r'):
                continue

            if '#' in line:


M docs/cli.md => docs/cli.md +0 -250
@@ 37,253 37,3 @@ 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
```


M docs/cli_commands.md => docs/cli_commands.md +10 -0
@@ 4,6 4,8 @@

## `qmk cformat`

*(dev mode)*

This command formats C code using clang-format. 

Run it with no arguments to format all core code that has been changed. Default checks `origin/master` with `git diff`, branch can be changed using `-b <branch_name>`


@@ 138,6 140,8 @@ qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]

## `qmk docs`

*(dev mode)*

This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.

**Usage**:


@@ 182,6 186,8 @@ qmk json2c [-o OUTPUT] filename

## `qmk kle2json`

*(dev mode)*

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**:


@@ 234,6 240,8 @@ qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]

## `qmk pyformat`

*(dev mode)*

This command formats python code in `qmk_firmware`.

**Usage**:


@@ 244,6 252,8 @@ 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**:


M docs/cli_development.md => docs/cli_development.md +11 -1
@@ 6,7 6,17 @@ This document has useful information for developers wishing to write new `qmk` s

The QMK CLI operates using the subcommand pattern made famous by git. The main `qmk` script is simply there to setup the environment and pick the correct entrypoint to run. Each subcommand is a self-contained module with an entrypoint (decorated by `@cli.subcommand()`) that performs some action and returns a shell returncode, or None.

*Tip*: Enable dev mode by `qmk config user.developer=True`
## Developer mode:

If you intend to maintain keyboards and/or contribute to QMK, you can enable the CLI's "Developer" mode:

`qmk config user.developer=True`

This will allow you to see all available subcommands.  
**Note:** You will have to install additional requirements:  
```bash
python3 -m pip install -r requirements-dev.txt
```

# Subcommands



M lib/python/qmk/cli/cformat.py => lib/python/qmk/cli/cformat.py +1 -1
@@ 35,7 35,7 @@ def cformat_run(files, all_files):
@cli.argument('-a', '--all-files', arg_only=True, action='store_true', help='Format all core files.')
@cli.argument('-b', '--base-branch', default='origin/master', help='Branch to compare to diffs to.')
@cli.argument('files', nargs='*', arg_only=True, help='Filename(s) to format.')
@cli.subcommand("Format C code according to QMK's style.")
@cli.subcommand("Format C code according to QMK's style.", hidden=True)
def cformat(cli):
    """Format C code according to QMK's style.
    """


M lib/python/qmk/cli/docs.py => lib/python/qmk/cli/docs.py +1 -1
@@ 7,7 7,7 @@ from milc import cli


@cli.argument('-p', '--port', default=8936, type=int, help='Port number to use.')
@cli.subcommand('Run a local webserver for QMK documentation.')
@cli.subcommand('Run a local webserver for QMK documentation.', hidden=True)
def docs(cli):
    """Spin up a local HTTPServer instance for the QMK docs.
    """


M lib/python/qmk/cli/kle2json.py => lib/python/qmk/cli/kle2json.py +1 -1
@@ 26,7 26,7 @@ class CustomJSONEncoder(json.JSONEncoder):

@cli.argument('filename', help='The KLE raw txt to convert')
@cli.argument('-f', '--force', action='store_true', help='Flag to overwrite current info.json')
@cli.subcommand('Convert a KLE layout to a Configurator JSON')
@cli.subcommand('Convert a KLE layout to a Configurator JSON', hidden=True)
def kle2json(cli):
    """Convert a KLE layout to QMK's layout format.
    """  # If filename is a path