diff --git a/README.asciidoc b/README.asciidoc
index 9aa34dc73..8f01a692c 100644
--- a/README.asciidoc
+++ b/README.asciidoc
@@ -1553,9 +1553,16 @@ New commands can be defined using the `:def` command.
     passed to this command
  * `-buffer-completion`: try buffer name completion on any parameter
     passed to this command
+ * `-command-completion`: try command completion on any parameter
+    passed to this command
  * `-shell-completion`: following string is a shell command which takes
     parameters as positional params and output one completion candidate
-    per line.
+    per line. The provided shell command will run after each keypress
+ * `-shell-candidates`: following string is a shell command which takes
+    parameters as positional params and output one completion candidate
+    per line. The provided shell command will run once at the beginning
+    of each completion session, candidates are cached and then used by
+    kakoune internal fuzzy engine
  * `-allow-override`: allow the new command to replace an existing one
     with the same name.
  * `-hidden`: do not show the command in command name completions
diff --git a/doc/manpages/commands.asciidoc b/doc/manpages/commands.asciidoc
index ae49bcb0b..73aee9dfa 100644
--- a/doc/manpages/commands.asciidoc
+++ b/doc/manpages/commands.asciidoc
@@ -254,9 +254,20 @@ New commands can be defined using the *define-command* command:
 *-buffer-completion*:::
 	try buffer name completion on any parameter passed to this command
 
+*-command-completion*:::
+	try command completion on any parameter passed to this command
+
 *-shell-completion*:::
 	following string is a shell command which takes parameters as
-	positional params and output one completion candidate per line
+	positional params and output one completion candidate per line.
+	The provided shell command will run after each keypress
+
+*-shell-candidates*:::
+	following string is a shell command which takes parameters as
+	positional params and output one completion candidate per line.
+	The provided shell command will run once at the beginning of each
+	completion session, candidates are cached and then used by kakoune
+	internal fuzzy engine
 
 *-allow-override*:::
 	allow the new command to replace an existing one with the same name