diff --git a/docs/repositories.md b/docs/repositories.md
index 889b961c4ed..f9dd873b84f 100644
--- a/docs/repositories.md
+++ b/docs/repositories.md
@@ -101,6 +101,14 @@ export POETRY_HTTP_BASIC_PYPI_PASSWORD=password
 See [Using environment variables]({{< relref "configuration#using-environment-variables" >}}) for more information
 on how to configure Poetry with environment variables.
 
+If your password starts with a dash (e.g. randomly generated tokens in a CI environment), it will be parsed as a
+command line option instead of a password.
+You can prevent this by adding double dashes to prevent any following argument from being parsed as an option.
+
+```bash
+poetry config -- http-basic.pypi myUsername -myPasswordStartingWithDash
+```
+
 #### Custom certificate authority and mutual TLS authentication
 Poetry supports repositories that are secured by a custom certificate authority as well as those that require
 certificate-based client authentication.  The following will configure the "foo" repository to validate the repository's