Sept 2021 Update: With the release of age v1.0, I’ve written a brand-new how-to post. The syntax below may be outdated now.

A while back I learned about age, which describes itself as “A simple, modern and secure encryption tool (and Go library) with small explicit keys, no config options, and UNIX-style composability.” As someone who’s struggled to learn and use PGP, I was intrigued!

There’s more info in this public Google Doc. Note: age is currently in beta.

Should I use age or rage?

There’s a implementation of age written in Rust called rage, which is inter-operable with age (the original golang version). Since I write some Rust, I chose to learn using rage, so all the commands below use rage. But given how rage and age are inter-operable, and I think the commands are the same, you could install age and still follow this post – just be sure to use age wherever you see rage.

Note that, as of this writing, age encrypts large files about twice as fast as rage.


To install rage, there are a couple options listed in the README on Github, including homebrew, (likewise with age, if you’re going that route).

Since I have an up-to-date version of the Rust language installed (1.46) already set up, I installed rage by running cargo install rage.

Using rage to encrypt a file with a passphrase

Let’s say we have a file called secrets.txt that we want to encrypt, such that only someone who knows a certain passphrase can decrypt it. We could just run:

$ rage -p -o secrets_encrypted.txt secrets.txt

Your terminal with then prompt you to enter your chosen the passphrase (if you don’t provide one, rage will generate a nice long one for you). I left the passphrase field blank so that rage would generate a passphrase for me. Here’s what I got:

$ rage -p -o secrets_encrypted.txt secrets.txt 
Using an autogenerated passphrase:

Rage created a new file called “secrets_encrypted.txt” that is encrypted and thus unreadable. The original secrets.txt is still in tact.

Decrypting file with a passphrase

Decrypting this file is simple. Just run

$ rage -d -o secrets_decrypted.txt secrets_encrypted.txt 

Running this command prompts you to enter the passphrase we set when encrypting the file. If you enter the passphrase correctly, rage decrypts the file into a new file called secrets_decrypted.txt. Again, the original “secrets_encrypted.txt” file is left in tact.

Using a public/private key-pair

Encrypting and decrypting files with secret passphrases can be useful, but one downside is that you have to securely get that passphrase to the other party. We can avoid this issue by using a public/private key-pair, which rage also supports.

When we installed rage, we got two executables: rage, which we’ve been using, and rage-keygen, which we haven’t used yet. rage-kleygen generate key-pairs for us. Let’s make a key-pair now.

$ rage-keygen > test_key.txt

Running this command will print our new public key.

Public key: age1s366ey709nfd29jpaapvq2s2w29wjv9y68v9vvz5rc5v3tgge4xq7afnej

It also places both this public key and our private or secret key in a file called test_key.txt. You should not share your secret key with anyone. But since this is a demonstration, I’ll copy and paste the contents of my new test_key.txt file below.

# created: 2020-09-08T15:39:39-04:00                                                                     
# public key: age1s366ey709nfd29jpaapvq2s2w29wjv9y68v9vvz5rc5v3tgge4xq7afnej                                         

As you can see, the file contains both our public key and our secret key (don’t share it with anyone!).

Encrypting a file for a public key

Let’s say someone else wants to encrypt a file for us, the holder of the key above. Let’s say the file they want to encrypt for us is file_for_keyholder_only.txt. They’d run

$ rage -o file_for_keyholder_only_encrypted.txt -r age1s366ey709nfd29jpaapvq2s2w29wjv9y68v9vvz5rc5v3tgge4xq7afnej file_for_keyholder_only.txt

That’s a long one, so let’s go over it. As above with the passphrase example, the -o flag tells rage where we’d like to place the output of this command – in this case, a new file that will be encrypted. Next is the -r flag, which stands for recipient. Here, we’re telling rage that we want to encrypt this file for a particular recipient, namely the owner of this specific public key (remember, public keys can be shared safely out in the open). Then, lastly, we tell rage which file we want to act on, in this case “file_for_keyholder_only.txt”, the file we wish to encrypt.

Once we hit enter, rage creates a new, encrypted file called file_for_keyholder_only_encrypted.txt.

Decrypting a file with a secret key

Now let’s say we receive a file that’s been encrypted for us using our public key. We want to decrypt it. We’ll run:

$ rage -o decrypted.txt -i test_key.txt -d file_for_keyholder_only_encrypted.txt

Which will decrypt the file to “decrypted.txt”. Note the -i flag pointing to the key-pair file (which contains the secret key), and the -d flag for decryption, which we’re already familiar with.

Creating a more permanent identity

If you want to create a key-pair that you’ll use more permanently, the age documentation recommends storing the key file in ~/.config/age/keys.txt. You’d do this by running

$ mkdir -p ~/.config/age
$ rage-keygen >> ~/.config/age/keys.txt

You can then use --identity ~/.config/age/keys.txt to use your saved key.

As before, you can share this public key broadly and publicly, so that others could encrypt files for you. For example, I now have a public age/rage key in a Github Gist that I link to from some of my social media accounts. Just remember: Don’t share your secret key!

Can you encrypt/decrypt text rather than a file?

What if you just want to encrypt a line or two of text, rather than a file? You can “pipe” in an echo command (note that rage requires that you encrypt using a public key, rather than a passphrase):

$ echo "secret message from echo" | rage -a -r age180d9ut0ff3zzkq6umq588p7zlqqetuf8nhxxfhsysmg4hjyt55lsjraysp 

which prints the encrypted text to the terminal:


The -a flag stands for “armor” and it tells rage to encrypt to a PEM encoded format, which is easier to copy and paste and move around in general.

Having this block of text printed to the terminal screen isn’t super helpful. We already know how to print it to a file, using the -o flag. But this time, how about we pipe it directly to the clipboard? If you’re using Linux and have xsel installed, you’d do this:

echo "secret message from echo" | rage -a -r age180d9ut0ff3zzkq6umq588p7zlqqetuf8nhxxfhsysmg4hjyt55lsjraysp | xsel --clipboard

(On Mac, try | pbcopy at the end, though I haven’t tested this. Other systems may have yet other tools for this – another popular one is called xclip.)

To decrypt an encrypted message currently in your clipboard with your stored key, you could run:

xsel --clipboard | rage -d -i ~/.config/age/keys.txt

which should print the decrypted message to the terminal screen.

More features

This guide is by no means exhaustive of what you can already do with these tools. Both rage and age currently have more features than I’ve outlined here. Check them out in each of their documentation!

To look forward to

It looks like the developer(s) of rage seem to be working on (and discussing) some sort of Yubikey plugin, though I’m not sure of its current status. That’d be pretty cool though!