4 files changed, 33 insertions, 0 deletions

diff --git a/docs/cli_commands.md b/docs/cli_commands.md
index fe6f06632..c970b1efa 100644
--- a/docs/cli_commands.md
+++ b/docs/cli_commands.md
@@ -212,6 +212,16 @@ This command is directory aware. It will automatically fill in KEYBOARD and/or K
 qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
 ```
 
+## `qmk clean`
+
+This command cleans up the `.build` folder. If `--all` is passed, any .hex or .bin files present in the `qmk_firmware` directory will also be deleted.
+
+**Usage**:
+
+```
+qmk clean [-a]
+```
+
 ---
 
 # Developer Commands
diff --git a/lib/python/qmk/cli/__init__.py b/lib/python/qmk/cli/__init__.py
index 47e1b4435..3868f94bb 100644
--- a/lib/python/qmk/cli/__init__.py
+++ b/lib/python/qmk/cli/__init__.py
@@ -8,6 +8,7 @@ from milc import cli
 
 from . import c2json
 from . import cformat
+from . import clean
 from . import compile
 from . import config
 from . import docs
diff --git a/lib/python/qmk/cli/clean.py b/lib/python/qmk/cli/clean.py
new file mode 100644
index 000000000..ec6501b76
--- /dev/null
+++ b/lib/python/qmk/cli/clean.py
@@ -0,0 +1,16 @@
+"""Clean the QMK firmware folder of build artifacts.
+"""
+from qmk.commands import run
+from milc import cli
+
+import shutil
+
+
+@cli.argument('-a', '--all', arg_only=True, action='store_true', help='Remove *.hex and *.bin files in the QMK root as well.')
+@cli.subcommand('Clean the QMK firmware folder of build artifacts.')
+def clean(cli):
+    """Runs `make clean` (or `make distclean` if --all is passed)
+    """
+    make_cmd = 'gmake' if shutil.which('gmake') else 'make'
+
+    run([make_cmd, 'distclean' if cli.args.all else 'clean'])
diff --git a/lib/python/qmk/tests/test_cli_commands.py b/lib/python/qmk/tests/test_cli_commands.py
index 7c261db6c..df5f047da 100644
--- a/lib/python/qmk/tests/test_cli_commands.py
+++ b/lib/python/qmk/tests/test_cli_commands.py
@@ -184,3 +184,9 @@ def test_c2json_nocpp():
     result = check_subcommand("c2json", "--no-cpp", "-kb", "handwired/onekey/pytest", "-km", "default", "keyboards/handwired/onekey/keymaps/pytest_nocpp/keymap.c")
     check_returncode(result)
     assert result.stdout.strip() == '{"keyboard": "handwired/onekey/pytest", "documentation": "This file is a keymap.json file for handwired/onekey/pytest", "keymap": "default", "layout": "LAYOUT", "layers": [["KC_ENTER"]]}'
+
+
+def test_clean():
+    result = check_subcommand('clean', '-a')
+    check_returncode(result)
+    assert result.stdout.count('done') == 2