From db8ed63595836be2fc0b879080a63f83865a4c3e Mon Sep 17 00:00:00 2001
From: Filippo Valsorda <hi@filippo.io>
Date: Wed, 24 Dec 2025 12:09:48 +0100
Subject: [PATCH] cmd/age-plugin-batchpass: add detailed warning

---
 cmd/age-plugin-batchpass/plugin-batchpass.go | 44 ++++++++++++++++++--
 1 file changed, 40 insertions(+), 4 deletions(-)

diff --git a/cmd/age-plugin-batchpass/plugin-batchpass.go b/cmd/age-plugin-batchpass/plugin-batchpass.go
index 3974d77..88f2777 100644
--- a/cmd/age-plugin-batchpass/plugin-batchpass.go
+++ b/cmd/age-plugin-batchpass/plugin-batchpass.go
@@ -17,14 +17,50 @@ import (
 const usage = `age-plugin-batchpass is an age 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.
 
 Usage:
 
-  AGE_PASSPHRASE=password age -e -j batchpass file.txt > file.txt.age
+    $ AGE_PASSPHRASE=password age -e -j batchpass file.txt > file.txt.age
 
-  AGE_PASSPHRASE=password age -d -j batchpass file.txt.age > file.txt
+    $ AGE_PASSPHRASE=password age -d -j batchpass file.txt.age > file.txt
 
 Alternatively, you can use AGE_PASSPHRASE_FD to read the passphrase from
 a file descriptor. Trailing newlines are stripped from the file contents.