diff --git a/doc/pages/commands.asciidoc b/doc/pages/commands.asciidoc
index 4c7a71f3..3be1ce1c 100644
--- a/doc/pages/commands.asciidoc
+++ b/doc/pages/commands.asciidoc
@@ -275,6 +275,16 @@ New commands can be defined using the *define-command* command:
     positional params and output one completion candidate per line.
     The provided shell command will run after each keypress
 
+    during the executing of the shell command, the following env vars are
+    available:
+
+    - *kak_token_to_complete*::::
+        Index of the token being completed in the command line.
+
+    - *kak_pos_in_token*::::
+        Position of the cursor inside the token being completed, in bytes
+        from token start.
+
 *-shell-candidates*:::
     following string is a shell command which takes parameters as
     positional params and output one completion candidate per line.
@@ -282,6 +292,12 @@ New commands can be defined using the *define-command* command:
     completion session, candidates are cached and then used by kakoune
     internal fuzzy engine
 
+    during the executing of the shell command, the following env vars are
+    available:
+
+    - *kak_token_to_complete*::::
+        Index of the token being completed in the command line.
+
 *-allow-override*:::
     allow the new command to replace an existing one with the same name