From 3d73da544d42a8ac15ad9082a602d4d4e3facac3 Mon Sep 17 00:00:00 2001
From: Filippo Valsorda <hi@filippo.io>
Date: Fri, 27 Dec 2019 23:48:29 +0100
Subject: [PATCH] cmd/age: add -help and README

---
 README.md      | 58 ++++++++++++++++++++++++++++++++++++++++++++++----
 cmd/age/age.go | 28 ++++++++++++++++++++++++
 2 files changed, 82 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 6a5f5733..7617f2c4 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,57 @@
-age is meant to be a simple, secure and modern encryption tool with small explicit keys, no config options, and UNIX-style composability. The spec is at [age-encryption.org/v1](https://age-encryption.org/v1).
+# age
 
-This implementation is in progress, and things will keep moving around, so it's not yet a good time to contribute, and it's definitely not a good time to rely on it.
+age is a simple, modern and secure file encryption tool.
 
-To discuss the spec or other age related topics, please email the mailing list at age-dev@googlegroups.com. Subscribe at [groups.google.com/d/forum/age-dev](https://groups.google.com/d/forum/age-dev) or by emailing age-dev+subscribe@googlegroups.com.
+I features small explicit keys, no config options, and UNIX-style composability.
 
-Development is sometimes livestreamed at [twitch.tv/filosottile](https://www.twitch.tv/filosottile).
+```
+$ age-keygen -o key.txt
+Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+$ tar cvz ~/data | age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data.tar.gz.age
+$ age -d -i key.txt -o data.tar.gz data.tar.gz.age
+```
+
+The format specification is at [age-encryption.org/v1](https://age-encryption.org/v1). To discuss the spec or other age related topics, please email the mailing list at age-dev@googlegroups.com. Subscribe at [groups.google.com/d/forum/age-dev](https://groups.google.com/d/forum/age-dev) or by emailing age-dev+subscribe@googlegroups.com.
+
+## Usage
+
+```
+Usage:
+    age -r RECIPIENT [-a] [-o OUTPUT] [INPUT]
+    age --decrypt [-i KEY] [-o OUTPUT] [INPUT]
+
+Options:
+    -o OUTPUT                   Write the result to the file at path OUTPUT.
+    -a, --armor                 Encrypt to a PEM encoded format.
+    -p, --passphrase            Encrypt with a passphrase.
+    -r, --recipient RECIPIENT   Encrypt to the specified RECIPIENT. Can be repeated.
+    -d, --decrypt               Decrypt the input to the output.
+    -i, --identity KEY          Use the private key file at path KEY. Can be repeated.
+
+INPUT defaults to standard input, and OUTPUT defaults to standard output.
+
+RECIPIENT can be an age public key, as generated by age-keygen, ("age1...")
+or an SSH public key ("ssh-ed25519 AAAA...", "ssh-rsa AAAA...").
+
+KEY is a path to a file with age secret keys, one per line
+(ignoring "#" prefixed comments and empty lines), or to an SSH key file.
+Multiple keys can be provided, and any unused ones will be ignored.
+```
+
+## Installation
+
+On macOS, use Homebrew.
+
+```
+brew tap filippo.io/age https://filippo.io/age
+brew install age
+```
+
+On Linux and Windows, use [the pre-built binaries](https://github.com/FiloSottile/age/releases) or build from source with Go 1.13+.
+
+```
+git clone https://filippo.io/age && cd age
+go build filippo.io/cmd/age/...
+```
+
+Help from new packagers is very welcome.
diff --git a/cmd/age/age.go b/cmd/age/age.go
index 6b4404b6..60fd169b 100644
--- a/cmd/age/age.go
+++ b/cmd/age/age.go
@@ -27,8 +27,36 @@ func (f *multiFlag) Set(value string) error {
 	return nil
 }
 
+const usage = `Usage:
+    age -r RECIPIENT [-a] [-o OUTPUT] [INPUT]
+    age --decrypt [-i KEY] [-o OUTPUT] [INPUT]
+
+Options:
+    -o OUTPUT                   Write the result to the file at path OUTPUT.
+    -a, --armor                 Encrypt to a PEM encoded format.
+    -p, --passphrase            Encrypt with a passphrase.
+    -r, --recipient RECIPIENT   Encrypt to the specified RECIPIENT. Can be repeated.
+    -d, --decrypt               Decrypt the input to the output.
+    -i, --identity KEY          Use the private key file at path KEY. Can be repeated.
+
+INPUT defaults to standard input, and OUTPUT defaults to standard output.
+
+RECIPIENT can be an age public key, as generated by age-keygen, ("age1...")
+or an SSH public key ("ssh-ed25519 AAAA...", "ssh-rsa AAAA...").
+
+KEY is a path to a file with age secret keys, one per line
+(ignoring "#" prefixed comments and empty lines), or to an SSH key file.
+Multiple keys can be provided, and any unused ones will be ignored.
+
+Example:
+    $ age-keygen -o key.txt
+    Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+    $ tar cvz ~/data | age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data.tar.gz.age
+    $ age -d -i key.txt -o data.tar.gz data.tar.gz.age`
+
 func main() {
 	_log.SetFlags(0)
+	flag.Usage = func() { fmt.Fprintf(os.Stderr, "%s\n", usage) }
 
 	var (
 		outFlag                          string