cli_development.md - # QMK CLI Development This document...

# QMK CLI Development
This document has useful information for developers wishing to write new `qmk`
subcommands.
# Overview
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.
## 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
[MILC]() is the CLI framework `qmk` uses to
handle argument parsing, configuration, logging, and many other features. It
lets you focus on writing your tool without wasting your time writing glue code.
Subcommands in the local CLI are always found in
`qmk_firmware/lib/python/qmk/cli`.
Let's start by looking at an example subcommand. This is
`lib/python/qmk/cli/hello.py`:
```python
"""QMK Python Hello World
This is an example QMK CLI script.
"""
from milc import cli
@cli.argument('-n', '--name', default='World', help='Name to greet.')
@cli.subcommand('QMK Hello World.')
def hello(cli):
"""Log a friendly greeting.
"""
cli.log.info('Hello, %s!', cli.config.hello.name)
```
First we import the `cli` object from `milc`. This is how we interact with the
user and control the script's behavior. We use `@cli.argument()` to define a
command line flag, `--name`. This also creates a configuration variable named
`hello.name` (and the corresponding `user.name`) which the user can set so they
don't have to specify the argument. The `cli.subcommand()` decorator designates
this function as a subcommand. The name of the subcommand will be taken from the
name of the function.
Once inside our function we find a typical "Hello, World!" program. We use
`cli.log` to access the underlying [Logger Object]

(), whose
behavior is user controllable. We also access the value for name supplied by the
user as `cli.config.hello.name`. The value for `cli.config.hello.name` will be
determined by looking at the `--name` argument supplied by the user, if not
provided it will use the value in the `qmk.ini` config file, and if neither of
those is provided it will fall back to the default supplied in the