2 files changed, 37 insertions, 1 deletions

diff --git a/docs/cli_commands.md b/docs/cli_commands.md
index c970b1efa..b10f5d499 100644
--- a/docs/cli_commands.md
+++ b/docs/cli_commands.md
@@ -178,6 +178,24 @@ Creates a keymap.json from a keymap.c.
 qmk c2json [--no-cpp] [-o OUTPUT] filename
 ```
 
+## `qmk lint`
+
+Checks over a keyboard and/or keymap and highlights common errors, problems, and anti-patterns.
+
+**Usage**:
+
+```
+qmk lint [-km KEYMAP] [-kb KEYBOARD] [--strict]
+```
+
+This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
+
+**Examples**:
+
+Do a basic lint check:
+
+    qmk lint -kb rominronin/katana60/rev2
+
 ## `qmk list-keyboards`
 
 This command lists all the keyboards currently defined in `qmk_firmware`
@@ -309,4 +327,3 @@ This command runs the python test suite. If you make changes to python code you
 ```
 qmk pytest
 ```
-
diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md
index d49d0d092..742b56572 100644
--- a/docs/hardware_keyboard_guidelines.md
+++ b/docs/hardware_keyboard_guidelines.md
@@ -3,6 +3,25 @@
 Since starting, QMK has grown by leaps and bounds thanks to people like you who contribute to creating and maintaining our community keyboards. As we've grown we've discovered some patterns that work well, and ask that you conform to them to make it easier for other people to benefit from your hard work.
 
 
+## Use QMK Lint
+
+We have provided a tool, `qmk lint`, which will let you check over your keyboard for problems. We suggest using it frequently while working on your keyboard and keymap. 
+
+Example passing check:
+
+```
+$ qmk lint -kb rominronin/katana60/rev2
+Ψ Lint check passed!
+```
+
+Example failing check:
+
+```
+$ qmk lint -kb clueboard/66/rev3
+☒ Missing keyboards/clueboard/66/rev3/readme.md
+☒ Lint check failed!
+```
+
 ## Naming Your Keyboard/Project
 
 All keyboard names are in lower case, consisting only of letters, numbers, and underscore (`_`). Names may not begin with an underscore. Forward slash (`/`) is used as a sub-folder separation character.