AGE(1)

📦
version 1.3.2 · 5 versions
, in alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable

bestie, you're looking at age(1) — the manual page for age, the simple, modern, and secure file encryption tool. It's giving cryptography, but make it cute. 💅

🌸 NAME 🌸

age — simple, modern, and secure file encryption. No cap. ✨

✨ SYNOPSIS ✨

okay so here's the shape of it, bestie:

age [--encrypt] (-r RECIPIENT | -R PATH)... [--armor] [-o OUTPUT]
[INPUT]
age [--encrypt] --passphrase [--armor] [-o OUTPUT] [INPUT]
age --decrypt [-i PATH | -j PLUGIN]... [-o OUTPUT] [INPUT]

💖 DESCRIPTION 💖

age encrypts or decrypts INPUT to OUTPUT, periodt. The INPUT argument is optional and defaults to standard input. Only a single INPUT file may be specified — one file, bestie, that's the rule. If -o is not specified, OUTPUT defaults to standard output.

If -p/--passphrase is specified, the file is encrypted with a passphrase requested interactively. Otherwise, it's encrypted to one or more RECIPIENTS specified with -r/--recipient or -R/--recipients-file. Every recipient can decrypt the file. 💖

In -d/--decrypt mode, passphrase-encrypted files are detected automatically and the passphrase is requested interactively. Otherwise, one or more IDENTITIES specified with -i/--identity are used to decrypt the file.

age encrypted files are binary and not malleable, with around 200 bytes of overhead per recipient, plus 16 bytes every 64KiB of plaintext. The math is mathing. 🧮✨

💅 OPTIONS 💅

  • -o, --output=OUTPUT — Write the encrypted or decrypted file to OUTPUT instead of standard output. If OUTPUT already exists, it will be overwritten. 😭 If you're encrypting without --armor, age will refuse to output binary to a TTY. This can be forced by specifying - as OUTPUT.
  • --version — Print the version and exit. That's it. 💅

🔐 Encryption options 🔐

  • -e, --encrypt — Encrypt INPUT to OUTPUT. This is the default, bestie. ✨
  • -r, --recipient=RECIPIENT — Encrypt to the explicitly specified RECIPIENT. See the RECIPIENTS AND IDENTITIES section for possible recipient formats. This option can be repeated and combined with other recipient flags, and the file can be decrypted by all provided recipients independently. The more the merrier. 🫶
  • -R, --recipients-file=PATH — Encrypt to the RECIPIENTS listed in the file at PATH, one per line. Empty lines and lines starting with # are ignored as comments. If PATH is -, the recipients are read from standard input. In this case, the INPUT argument must be specified. This option can be repeated and combined with other recipient flags, and the file can be decrypted by all provided recipients independently. 💖
  • -p, --passphrase — Encrypt with a passphrase, requested interactively from the terminal. age will offer to auto-generate a secure passphrase. This option can't be used with other recipient flags. 🚫
  • -a, --armor — Encrypt to an ASCII-only "armored" encoding. age armor is a strict version of PEM with type AGE ENCRYPTED FILE, canonical "strict" Base64, no headers, and no support for leading and trailing extra data. Decryption transparently detects and decodes ASCII armoring. It's giving armor but make it text. 🛡️✨
  • -i, --identity=PATH — Encrypt to the RECIPIENTS corresponding to the IDENTITIES listed in the file at PATH. This is equivalent to converting the file at PATH to a recipients file with age-keygen -y and then passing that to -R/--recipients-file. For the format of PATH, see the definition of -i/--identity in the Decryption options section. -e/--encrypt must be explicitly specified when using -i/--identity in encryption mode to avoid confusion. Bestie, read the room and pass the flag. 😌
  • -j PLUGIN — Encrypt using the data-less plugin PLUGIN. This is equivalent to using -i/--identity with a file that contains a single plugin IDENTITY that encodes no plugin-specific data. -e/--encrypt must be explicitly specified when using -j in encryption mode to avoid confusion. 🧩

🔓 Decryption options 🔓

  • -d, --decrypt — Decrypt INPUT to OUTPUT. If INPUT is passphrase encrypted, it will be automatically detected and the passphrase will be requested interactively. Otherwise, the IDENTITIES specified with -i/--identity are used. ASCII armoring is transparently detected and decoded. ✨
  • -i, --identity=PATH — Decrypt using the IDENTITIES at PATH. PATH may be one of the following:
    • a. A file listing IDENTITIES one per line. Empty lines and lines starting with # are ignored as comments.
    • b. A passphrase encrypted age file, containing IDENTITIES one per line like above. The passphrase is requested interactively. Note that passphrase-protected identity files are not necessary for most use cases, where access to the encrypted identity file implies access to the whole system.
    • c. An SSH private key file, in PKCS#1, PKCS#8, or OpenSSH format. If the private key is password-protected, the password is requested interactively only if the SSH identity matches the file. See the SSH keys section for more information, including supported key types.
    • d. -, causing one of the options above to be read from standard input. In this case, the INPUT argument must be specified.

This option can be repeated. Identities are tried in the order in which are provided, and the first one matching one of the file's recipients is used. Unused identities are ignored, but it is an error if the INPUT file is passphrase-encrypted and -i/--identity is specified. Bestie, that's the rule. 💅

  • -j PLUGIN — Decrypt using the data-less plugin PLUGIN. This is equivalent to using -i/--identity with a file that contains a single plugin IDENTITY that encodes no plugin-specific data. 🧩

🫶 RECIPIENTS AND IDENTITIES 🫶

RECIPIENTS are public values, like a public key, that a file can be encrypted to. IDENTITIES are private values, like a private key, that allow decrypting a file encrypted to the corresponding RECIPIENT. Public = shareable, private = keep it close. iykyk. 🔐

🧚 Native keys 🧚

Native age key pairs are generated with age-keygen(1), and provide small encodings and strong encryption based on X25519 for classic keys, and X25519 + ML-KEM-768 for post-quantum hybrid keys. The post-quantum hybrid keys are secure against future quantum computers and are the recommended recipient type for most applications. Future-proofing is main character energy. 👑✨

A hybrid RECIPIENT encoding begins with age1pq1 and looks like the following:

age1pq167[... 1950 more characters ...]

A hybrid IDENTITY encoding begins with AGE-SECRET-KEY-PQ-1 and looks like the following:

AGE-SECRET-KEY-PQ-1K30MYPZAHAXHR22YHH27EGDVLU0QNSUH3DSV7J7NR3X6D9LHXNWSDLTV4T

A classic RECIPIENT encoding begins with age1 and looks like the following:

age1gde3ncmahlqd9gg50tanl99r960llztrhfapnmx853s4tjum03uqfssgdh

A classic IDENTITY encoding begins with AGE-SECRET-KEY-1 and looks like the following:

AGE-SECRET-KEY-1KTYK6RVLN5TAPE7VF6FQQSKZ9HWWCDSKUGXXNUQDWZ7XXT5YK5LSF3UTKQ
⚠️ A file can't be encrypted to both post-quantum and classic keys, as that would defeat the post-quantum security of the encryption. So don't mix those vibes, bestie. 💀

An encrypted file can't be linked to the native recipient it's encrypted to without access to the corresponding identity. Privacy stays winning. 🌸

🔑 SSH keys 🔑

As a convenience feature, age also supports encrypting to RSA or Ed25519 ssh(1) keys. RSA keys must be at least 2048 bits. This feature employs more complex cryptography, and should only be used when a native key is not available for the recipient. Note that SSH keys might not be protected long-term by the recipient, since they are revokable when used only for authentication. Lowkey a use-when-needed situation. 🫶

A RECIPIENT encoding is an SSH public key in authorized_keys format (see the AUTHORIZED_KEYS FILE FORMAT section of sshd(8)), starting with ssh-rsa or ssh-ed25519, like the following:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDULTit0KUehbi[...]GU4BtElAbzh8=
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH9pO5pz22JZEas[...]l1uZc31FGYMXa

The comment at the end of the line, if present, is ignored. ✨

In recipient files passed to -R/--recipients-file, unsupported but valid SSH public keys are ignored with a warning, to facilitate using authorized_keys or GitHub .keys files. (See EXAMPLES.) Very "drop it in and go" of them. 💅

An IDENTITY is an SSH private key file passed individually to -i/--identity. Note that keys held on hardware tokens such as YubiKeys or accessed via ssh-agent(1) are not supported. Not me finding out the hard way. 😭

An encrypted file can be linked to the SSH public key it was encrypted to. This is so that age can identify the correct SSH private key before requesting its password, if any. It's giving thoughtful. 🌸

🧩 Plugins 🧩

age can be extended through plugins. A plugin is only loaded if a corresponding RECIPIENT or IDENTITY is specified. (Simply decrypting a file encrypted with a plugin will not cause it to load, for security reasons among others.) Safety first, bestie. 🛡️

A RECIPIENT for a plugin named example starts with age1example1, while an IDENTITY starts with AGE-PLUGIN-EXAMPLE-1. They both encode arbitrary plugin-specific data, and are generated by the plugin. Cute little namespace moment. 🎀

When either is specified, age searches for age-plugin-example in the PATH and executes it to perform the file header encryption or decryption. The plugin may request input from the user through age to complete the operation. Teamwork makes the dream work. 🫶

Plugins can be freely mixed with other plugins or natively supported keys. No gatekeeping. ✨

A plugin is not bound to only encrypt or decrypt files meant for or generated by the plugin. For example, a plugin can be used to decrypt files encrypted to a native X25519 RECIPIENT or even with a passphrase. Similarly, a plugin can encrypt a file such that it can be decrypted without the use of any plugin. Flexible icon behavior. 💅

Plugins for which the IDENTITY/RECIPIENT distinction doesn't make sense (such as a symmetric encryption plugin) may generate only an IDENTITY and instruct the user to perform encryption with the -e/--encrypt and -i/--identity flags. Plugins for which the concept of separate identities doesn't make sense (such as a password-encryption plugin) may instruct the user to use the -j flag. Bestie, just follow the plugin's instructions, fr fr. 🧩

age can natively encrypt to recipients starting with age1tag1 (using P-256 ECDH) or age1tagpq1 (using the ML-KEM-768 + P-256 post-quantum hybrid). These are intended to be the public side of private keys held in hardware. Hardware girlies, rise. 🔑✨

They are directly supported to avoid the need to install the plugin, which may be platform-specific, on the encrypting side. Convenience ate. 💅

The tag reduces privacy, by allowing an observer to correlate files with a recipient (but not files amongst them without knowledge of the recipient), but this is also a desirable property for hardware keys that require user interaction for each decryption operation. A little tradeoff, but make it make sense. 🌈

💀 EXIT STATUS 💀

okay so here's the vibe check on how age leaves the chat:

  • 0 — it exits 0 if and only if encryption or decryption is successful for the full length of the input. like, the whole thing. no half-sending. 👑
no cap, this is the dramatic part: if an error happens during decryption, partial output might still get written out — but only if it was possible to securely authenticate it. No unauthenticated output is ever released. ever. not even a crumb. 🫶

🌈 BACKWARDS COMPATIBILITY 🌈

Files encrypted with a stable version (not alpha, beta, or release candidate) of age, or with any v1.0.0 beta or release candidate, will decrypt with any later version of the tool. so your old locked-up stuff stays unlocked, iykyk. 💖

If decrypting older files poses a security risk, doing so might cause an error by default. In this case, a flag will be provided to force the operation. so like — the tool might be ✨protective✨ of you by default, and there'll be an escape hatch flag if you really need it. 🚪

🎀 EXAMPLES 🎀

✨ the full pipeline: generate a post-quantum identity, encrypt, decrypt ✨

$ age-keygen -pq -o key.txt
Public key: age1pq167[... 1950 more characters ...]

$ tar cvz ~/data | age -r age1pq167[...] > data.tar.gz.age

$ age -d -o data.tar.gz -i key.txt data.tar.gz.age

like, tar it up, pipe it straight into age, and reverse it later with your key file. obsessed with the pipeline energy 🌸

🦋 encrypt example.jpg to multiple recipients 🦋

and output to example.jpg.age, obviously:

$ age -o example.jpg.age -r age1pq167[...] -r age1pq1e3[...] example.jpg

two -r flags, two besties getting the file. 💅

💜 encrypt to a list of recipients 💜

$ cat > recipients.txt
# Alice
age1pq167[... 1950 more characters ...]
# Bob
age1pq1e3[... 1950 more characters ...]

$ age -R recipients.txt example.jpg > example.jpg.age

the # lines are just lil comments for your own sanity, and the capital -R is the "read this whole list" flag. 🫶

🔥 encrypt and decrypt a file using a passphrase 🔥

$ age -p secrets.txt > secrets.txt.age
Enter passphrase (leave empty to autogenerate a secure one):
Using the autogenerated passphrase "release-response-step-brand-wrap-ankle-pair-unusual-sword-train".

$ age -d secrets.txt.age > secrets.txt
Enter passphrase:

lowkey the best part: leave it empty and it literally invents a whole secure passphrase for you. and that passphrase? "release-response-step-brand-wrap-ankle-pair-unusual-sword-train". iconic. 😭

🧚 passphrase-protected identity file: the combo move 🧚

$ age-keygen | age -p > key.age
Public key: age1yhm4gctwfmrpz87tdslm550wrx6m79y9f2hdzt0lndjnehwj0ukqrjpyx5
Enter passphrase (leave empty to autogenerate a secure one):
Using the autogenerated passphrase "hip-roast-boring-snake-mention-east-wasp-honey-input-actress".

$ age -r age1yhm4gctwfmrpz87tdslm550wrx6m79y9f2hdzt0lndjnehwj0ukqrjpyx5 secrets.txt > secrets.txt.age

$ age -d -i key.age secrets.txt.age > secrets.txt
Enter passphrase for identity file "key.age":

so you pipe the freshly generated key straight into age -p and boom, your identity file is itself encrypted. main character energy. 👑

⭐ encrypt and decrypt with an SSH public key ⭐

$ age -R ~/.ssh/id_ed25519.pub example.jpg > example.jpg.age

$ age -d -i ~/.ssh/id_ed25519 example.jpg.age > example.jpg

you already have SSH keys, bestie. age said "say less." 🔑

🌟 encrypt and decrypt with age-plugin-yubikey 🌟

$ age-plugin-yubikey # run interactive setup, generate identity file and obtain recipient

$ age -r age1yubikey1qwt50d05nh5vutpdzmlg5wn80xq5negm4uj9ghv0snvdd3yysf5yw3rhl3t secrets.txt > secrets.txt.age

$ age -d -i age-yubikey-identity-388178f3.txt secrets.txt.age

first line is the interactive setup (it makes your identity file and hands you the recipient), then it's just normal age business with a hardware key. hardware-backed decryption?? slay. 💖

🌈 encrypt to the SSH keys of a GitHub user 🌈

$ curl https://github.com/benjojo.keys | age -R - example.jpg > example.jpg.age

fetch their public keys over curl, pipe into age -R - (the - means "read the recipient list from stdin", fr fr), done. ✨

👀 SEE ALSO 👀

go read those next, they're the supporting cast and they ate. 🎀

💅 AUTHORS 💅

Filippo Valsorda age@filippo.io

and that's the whole page, bestie!! 🦋 this was the AGE(1) manual page from August 2026 — shipped with the tool itself, no separate version number, periodt. now go encrypt something and feel like the main character. 💖✨🎀

📦 where this page comes from