qmk_firmware

QMK firmware for my keyboards (Corne, Sweep Ferris) and trackball (Ploopy Adept)
Log | Files | Refs | Submodules | LICENSE

cli_configuration.md (4080B)

      1 # QMK CLI Configuration
      2 
      3 This document explains how `qmk config` works.
      4 
      5 # Introduction
      6 
      7 Configuration for the QMK CLI is a key/value system. Each key consists of a subcommand and an argument name separated by a period. This allows for a straightforward and direct translation between config keys and the arguments they set.
      8 
      9 ## Simple Example
     10 
     11 As an example let's look at the command `qmk compile --keyboard clueboard/66/rev4 --keymap default`.
     12 
     13 There are two command line arguments that could be read from configuration instead:
     14 
     15 * `compile.keyboard`
     16 * `compile.keymap`
     17 
     18 Let's set these now:
     19 
     20 ```
     21 $ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default
     22 compile.keyboard: None -> clueboard/66/rev4
     23 compile.keymap: None -> default
     24 Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
     25 ```
     26 
     27 Now I can run `qmk compile` without specifying my keyboard and keymap each time.
     28 
     29 ## Setting User Defaults
     30 
     31 Sometimes you want to share a setting between multiple commands. For example, multiple commands take the argument `--keyboard`. Rather than setting this value for every command you can set a user value which will be used by any command that takes that argument.
     32 
     33 Example:
     34 
     35 ```
     36 $ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default
     37 user.keyboard: None -> clueboard/66/rev4
     38 user.keymap: None -> default
     39 Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
     40 ```
     41 
     42 # CLI Documentation (`qmk config`)
     43 
     44 The `qmk config` command is used to interact with the underlying configuration. When run with no argument it shows the current configuration. When arguments are supplied they are assumed to be configuration tokens, which are strings containing no spaces with the following form:
     45 
     46 ```
     47 <subcommand|general|default>[.<key>][=<value>]
     48 ```
     49 
     50 ## Setting Configuration Values
     51 
     52 You can set configuration values by putting an equal sign (=) into your config key. The key must always be the full `<section>.<key>` form.
     53 
     54 Example:
     55 
     56 ```
     57 $ qmk config default.keymap=default
     58 default.keymap: None -> default
     59 Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
     60 ```
     61 
     62 ## Reading Configuration Values
     63 
     64 You can read configuration values for the entire configuration, a single key, or for an entire section. You can also specify multiple keys to display more than one value.
     65 
     66 ### Entire Configuration Example
     67 
     68 ```
     69 qmk config
     70 ```
     71 
     72 ### Whole Section Example
     73 
     74 ```
     75 qmk config compile
     76 ```
     77 
     78 ### Single Key Example
     79 
     80 ```
     81 qmk config compile.keyboard
     82 ```
     83 
     84 ### Multiple Keys Example
     85 
     86 ```
     87 qmk config user compile.keyboard compile.keymap
     88 ```
     89 
     90 ## Deleting Configuration Values
     91 
     92 You can delete a configuration value by setting it to the special string `None`.
     93 
     94 Example:
     95 
     96 ```
     97 $ qmk config default.keymap=None
     98 default.keymap: default -> None
     99 Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
    100 ```
    101 
    102 ## Multiple Operations
    103 
    104 You can combine multiple read and write operations into a single command. They will be executed and displayed in order:
    105 
    106 ```
    107 $ qmk config compile default.keymap=default compile.keymap=None
    108 compile.keymap=skully
    109 compile.keyboard=clueboard/66_hotswap/gen1
    110 default.keymap: None -> default
    111 compile.keymap: skully -> None
    112 Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
    113 ```
    114 
    115 # User Configuration Options
    116 
    117 | Key | Default Value | Description |
    118 |-----|---------------|-------------|
    119 | user.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
    120 | user.keymap | None | The keymap name (Example: `default`) |
    121 | user.name | None | The user's GitHub username. |
    122 
    123 # All Configuration Options
    124 
    125 | Key | Default Value | Description |
    126 |-----|---------------|-------------|
    127 | compile.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
    128 | compile.keymap | None | The keymap name (Example: `default`) |
    129 | hello.name | None | The name to greet when run. |
    130 | new_keyboard.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
    131 | new_keyboard.keymap | None | The keymap name (Example: `default`) |