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

This preview shows page 1 - 3 out of 5 pages.

# QMK CLI DevelopmentThis document has useful information for developers wishing to write new `qmk` subcommands.# OverviewThe 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 shellreturncode, or None.## Developer mode:If you intend to maintain keyboards and/or contribute to QMK, you can enable theCLI'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: ```bashpython3 -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 WorldThis 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 thename 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 theuser 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

Upload your study docs or become a

Course Hero member to access this document

Upload your study docs or become a

Course Hero member to access this document

End of preview. Want to read all 5 pages?

Upload your study docs or become a

Course Hero member to access this document

Term
Fall
Professor
N/A
Tags

  • Left Quote Icon

    Student Picture

  • Left Quote Icon

    Student Picture

  • Left Quote Icon

    Student Picture