docs/cli_configuration.md

   1 # QMK CLI Configuration
   2
   3 This document explains how `qmk config` works.
   4
   5 # Introduction
   6
   7 Configuration for 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     <subcommand|general|default>[.<key>][=<value>]
  47
  48 ## Setting Configuration Values
  49
  50 You can set configuration values by putting an equal sign (=) into your config key. The key must always be the full `<section>.<key>` form.
  51
  52 Example:
  53
  54 ```
  55 $ qmk config default.keymap=default
  56 default.keymap: None -> default
  57 Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
  58 ```
  59
  60 ## Reading Configuration Values
  61
  62 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.
  63
  64 ### Entire Configuration Example
  65
  66     qmk config
  67
  68 ### Whole Section Example
  69
  70     qmk config compile
  71
  72 ### Single Key Example
  73
  74     qmk config compile.keyboard
  75
  76 ### Multiple Keys Example
  77
  78     qmk config user compile.keyboard compile.keymap
  79
  80 ## Deleting Configuration Values
  81
  82 You can delete a configuration value by setting it to the special string `None`.
  83
  84 Example:
  85
  86 ```
  87 $ qmk config default.keymap=None
  88 default.keymap: default -> None
  89 Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
  90 ```
  91
  92 ## Multiple Operations
  93
  94 You can combine multiple read and write operations into a single command. They will be executed and displayed in order:
  95
  96 ```
  97 $ qmk config compile default.keymap=default compile.keymap=None
  98 compile.keymap=skully
  99 compile.keyboard=clueboard/66_hotswap/gen1
 100 default.keymap: None -> default
 101 compile.keymap: skully -> None
 102 Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
 103 ```
 104
 105 # User Configuration Options
 106
 107 | Key | Default Value | Description |
 108 |-----|---------------|-------------|
 109 | user.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
 110 | user.keymap | None | The keymap name (Example: `default`) |
 111 | user.name | None | The user's github username. |
 112
 113 # All Configuration Options
 114
 115 | Key | Default Value | Description |
 116 |-----|---------------|-------------|
 117 | compile.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
 118 | compile.keymap | None | The keymap name (Example: `default`) |
 119 | hello.name | None | The name to greet when run. |
 120 | new_keyboard.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
 121 | new_keyboard.keymap | None | The keymap name (Example: `default`) |