doc: include warning in age-plugin-batchpass(1)

Author: FiloSottile

cmd/age-plugin-batchpass/plugin-batchpass.go

@@ -17,7 +17,7 @@ import (
 const usage = `age-plugin-batchpass is an age plugin that enables non-interactive
 passphrase-based encryption and decryption using environment variables.
 
-WARNING:
+WARNING: IN 90% OF CASES, YOU DON'T NEED THIS PLUGIN.
 
 This functionality is not built into the age CLI because most applications
 should use native keys instead of scripting passphrase-based encryption.

doc/age-plugin-batchpass.1.ronn

@@ -4,15 +4,51 @@ age-plugin-batchpass(1) -- non-interactive passphrase encryption plugin for age(
 ## SYNOPSIS
 
 `age` `-e` `-j` `batchpass`<br>
-`age` `-d` `-j` `batchpass`
+`age` `-d` `-j` `batchpass`<br>
 
 ## DESCRIPTION
 
 `age-plugin-batchpass` is an age(1) plugin that enables non-interactive
 passphrase-based encryption and decryption using environment variables.
 
-It is not built into the age CLI because most applications should use
-native keys instead of scripting passphrase-based encryption.
+## WARNING
+
+This functionality is not built into the age CLI because most applications
+should use native keys instead of scripting passphrase-based encryption.
+
+Humans are notoriously bad at remembering and generating strong passphrases.
+age uses scrypt to partially mitigate this, which is necessarily very slow.
+
+If a computer will be doing the remembering anyway, you can and should use
+native keys instead. There is no need to manage separate public and private
+keys, you encrypt directly to the private key:
+
+    $ age-keygen -o key.txt
+    $ age -e -i key.txt file.txt > file.txt.age
+    $ age -d -i key.txt file.txt.age > file.txt
+
+Likewise, you can store a native identity string in an environment variable
+or through your CI secrets manager and use it to encrypt and decrypt files
+non-interactively:
+
+    $ export AGE_SECRET=$(age-keygen)
+    $ age -e -i <(echo "$AGE_SECRET") file.txt > file.txt.age
+    $ age -d -i <(echo "$AGE_SECRET") file.txt.age > file.txt
+
+The age CLI also natively supports passphrase-encrypted identity files, so you
+can use that functionality to non-interactively encrypt multiple files such that
+you will be able to decrypt them later by entering the same passphrase:
+
+    $ age-keygen -pq | age -p -o encrypted-identity.txt
+    Public key: age1pq1cd[... 1950 more characters ...]
+    Enter passphrase (leave empty to autogenerate a secure one):
+    age: using autogenerated passphrase "eternal-erase-keen-suffer-fog-exclude-huge-scorpion-escape-scrub"
+    $ age -r age1pq1cd[... 1950 more characters ...] file.txt > file.txt.age
+    $ age -d -i encrypted-identity.txt file.txt.age > file.txt
+    Enter passphrase for identity file "encrypted-identity.txt":
+
+Finally, when using this plugin care should be taken not to let the password be
+persisted in the shell history or leaked to other users on multi-user systems.
 
 ## ENVIRONMENT