auri.ee
keyboard stuff
1# QMK CLI Configuration
2
3This document explains how `qmk config` works.
4
5# Introduction
6
7Configuration 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
11As an example let's look at the command `qmk compile --keyboard clueboard/66/rev4 --keymap default`.
12
13There are two command line arguments that could be read from configuration instead:
14
15* `compile.keyboard`
16* `compile.keymap`
17
18Let's set these now:
19
20```
21$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default
22compile.keyboard: None -> clueboard/66/rev4
23compile.keymap: None -> default
24Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
25```
26
27Now I can run `qmk compile` without specifying my keyboard and keymap each time.
28
29## Setting User Defaults
30
31Sometimes 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
33Example:
34
35```
36$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default
37user.keyboard: None -> clueboard/66/rev4
38user.keymap: None -> default
39Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
40```
41
42# CLI Documentation (`qmk config`)
43
44The `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
52You can set configuration values by putting an equal sign (=) into your config key. The key must always be the full `<section>.<key>` form.
53
54Example:
55
56```
57$ qmk config default.keymap=default
58default.keymap: None -> default
59Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
60```
61
62## Reading Configuration Values
63
64You 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```
69qmk config
70```
71
72### Whole Section Example
73
74```
75qmk config compile
76```
77
78### Single Key Example
79
80```
81qmk config compile.keyboard
82```
83
84### Multiple Keys Example
85
86```
87qmk config user compile.keyboard compile.keymap
88```
89
90## Deleting Configuration Values
91
92You can delete a configuration value by setting it to the special string `None`.
93
94Example:
95
96```
97$ qmk config default.keymap=None
98default.keymap: default -> None
99Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
100```
101
102## Multiple Operations
103
104You 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
108compile.keymap=skully
109compile.keyboard=clueboard/66_hotswap/gen1
110default.keymap: None -> default
111compile.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`) |