| name | gpg-encrypt |
| description | Encrypt a file or text with GPG to one or more recipients (asymmetric) or with a passphrase (symmetric). Use when the user wants to send confidential data to someone whose public key they have, or lock a file with a password. Defaults to ASCII-armored output and refuses to encrypt to keys with marginal/unknown trust unless the user confirms. |
Encrypt with GPG
When to use
The user wants to encrypt a file, message, or directory tarball — either to a recipient (asymmetric, using their public key) or with a passphrase (symmetric).
Decide: asymmetric or symmetric?
- Asymmetric (
-r <recipient>): you have the recipient's public key. Only they can decrypt. Use this for sending to someone else.
- Symmetric (
-c): no recipient — just a passphrase. Anyone with the passphrase can decrypt. Use for at-rest file encryption when you don't want to manage keys.
Asymmetric encryption
Verify recipient's key is on the keyring:
gpg --list-keys "<recipient-email>"
If missing, ask the user for the recipient's .asc public key file and import:
gpg --import <recipient.asc>
Encrypt:
gpg --armor --recipient <recipient-email> --output <file>.asc --encrypt <file>
For multiple recipients (each can decrypt independently):
gpg --armor -r alice@example.com -r bob@example.com -o <file>.asc -e <file>
Drop --armor for binary .gpg output (smaller, but not paste-friendly).
Sign-and-encrypt (recipient gets cryptographic proof it came from you):
gpg --armor --sign --recipient <recipient-email> --output <file>.asc --encrypt <file>
Symmetric encryption (passphrase only)
gpg --symmetric --armor --output <file>.asc <file>
GPG will prompt for the passphrase interactively. Defaults to AES256 in modern GPG (≥2.1).
To encrypt a directory, tar it first:
tar czf - <dir>/ | gpg --symmetric --armor --output <dir>.tar.gz.asc
Encrypting text snippets (not a file)
For ad-hoc text — pipe via stdin:
echo "secret text" | gpg --armor --recipient <email> --encrypt
The armored ciphertext goes to stdout; redirect to a file or copy from terminal.
Trust warnings
If the recipient's key is marginal or unknown trust, GPG warns: "There is no assurance this key belongs to the named user". Surface this to the user — don't auto-confirm with --trust-model always. If they're confident the key is genuine (verified the fingerprint out-of-band), they can either sign it locally:
gpg --lsign-key <recipient-email>
…or pass --trust-model always for a one-off encryption. Recommend the former for keys they'll use repeatedly.
Notes
--armor (ASCII-armored output, .asc) is best for email/paste/copy. Binary .gpg is smaller for at-rest storage.- Never pass passphrases on the command line — let GPG prompt. If you must (e.g. inside a script), use
--pinentry-mode loopback --passphrase-fd 0 and pipe the passphrase from a secrets manager, never hard-code.
