diff --git a/docs/README.md b/docs/README.md
index 9694e628..d14b3bfe 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1247,12 +1247,18 @@ https -A bearer -a token pie.dev/bearer
 
 ### Password prompt
 
+If you omit the password part of `--auth, -a`, HTTPie securely prompts you for it:
+
 ```bash
 $ http -a username pie.dev/basic-auth/username/password
 ```
 
+Please note that when you use [`--session`](#sessions), prompted passwords are persisted in sessions files .
+
 ### Empty password
 
+To send an empty password without being prompted for it, include a trailing colon in the credentials:
+
 ```bash
 $ http -a username: pie.dev/headers
 ```