sq: Reword and reorder the cli.

3 files changed, 536 insertions, 440 deletions

diff --git a/sq/src/sq-usage.rs b/sq/src/sq-usage.rs
index b1741eba..4a8d5a2d 100644
--- a/sq/src/sq-usage.rs
+++ b/sq/src/sq-usage.rs
@@ -9,15 +9,21 @@
 //!     sq [FLAGS] [OPTIONS] <SUBCOMMAND>
 //!
 //! FLAGS:
-//!     -f, --force      Overwrite existing files
-//!     -h, --help       Prints help information
-//!     -V, --version    Prints version information
+//!     -f, --force
+//!             Overwrites existing files
+//!
+//!     -h, --help
+//!             Prints help information
+//!
+//!     -V, --version
+//!             Prints version information
+//!
 //!
 //! OPTIONS:
 //!         --known-notation <NOTATION>...
-//!             The notation name is considered known. This is used when validating
-//!             signatures. Signatures that have unknown notations with the critical
-//!             bit set are considered invalid.
+//!             Adds NOTATION to the list of known notations. This is used when
+//!             validating signatures. Signatures that have unknown notations with
+//!             the critical bit set are considered invalid.
 //!
 //! SUBCOMMANDS:
 //!     encrypt             Encrypts a message
@@ -25,16 +31,16 @@
 //!     sign                Signs messages or data files
 //!     verify              Verifies signed messages or detached signatures
 //!     merge-signatures    Merges two signatures
-//!     key                 Manipulates keys
-//!     certring            Manipulates certificate rings
-//!     certify             Certify a User ID for a Certificate
-//!     autocrypt           Autocrypt support
+//!     key                 Manages keys
+//!     certring            Manages collections of certificates
+//!     certify             Certifies a User ID for a Certificate
+//!     autocrypt           Communicates certificates using Autocrypt
 //!     keyserver           Interacts with keyservers
 //!     wkd                 Interacts with Web Key Directories
-//!     armor               Applies ASCII Armor to a file
-//!     dearmor             Removes ASCII Armor from a file
+//!     armor               Converts binary data to ASCII
+//!     dearmor             Converts ASCII to binary
 //!     inspect             Inspects data, like file(1)
-//!     packet              Packet manipulation
+//!     packet              Low-level packet manipulation
 //!     help                Prints this message or the help of the given
 //!                         subcommand(s)
 //! ```
@@ -48,13 +54,18 @@
 //!     sq encrypt [FLAGS] [OPTIONS] [--] [FILE]
 //!
 //! FLAGS:
-//!     -B, --binary                Emit binary data
-//!     -h, --help                  Prints help information
-//!     -s, --symmetric             Encrypt with a password (can be given multiple
-//!                                 times)
-//!         --use-expired-subkey    If a certificate has only expired encryption-
-//!                                 capable subkeys, fall back to using
-//!                                 the one that expired last
+//!     -B, --binary
+//!             Emits binary data
+//!
+//!     -h, --help
+//!             Prints help information
+//!
+//!     -s, --symmetric
+//!             Adds a password to encrypt with.  The message can be decrypted with
+//!             either one of the recipient's keys, or any password.
+//!         --use-expired-subkey
+//!             If a certificate has only expired encryption-capable subkeys, falls
+//!             back to using the one that expired last
 //!
 //! OPTIONS:
 //!         --compression <KIND>
@@ -64,21 +75,24 @@
 //!             Selects what kind of keys are considered for encryption.  Transport
 //!             select subkeys marked as suitable for transport encryption, rest
 //!             selects those for encrypting data at rest, and all selects all
-//!             encryption-capable subkeys [default: all]  [possible values:
+//!             encryption-capable subkeys. [default: all]  [possible values:
 //!             transport, rest, all]
-//!     -o, --output <FILE>                    Sets the output file to use
+//!     -o, --output <FILE>
+//!             Writes to FILE or stdout if omitted
+//!
 //!         --recipient-cert <CERT-RING>...
-//!             Recipients to encrypt for, given as a file (can be given multiple
-//!             times)
+//!             Encrypts for all recipients in CERT-RING
+//!
 //!         --signer-key <KEY>...
-//!             Secret key to sign with, given as a file (can be given multiple
-//!             times)
+//!             Signs the message with KEY
+//!
 //!     -t, --time <TIME>
 //!             Chooses keys valid at the specified time and sets the signature's
 //!             creation time
 //!
 //! ARGS:
-//!     <FILE>    Sets the input file to use
+//!     <FILE>
+//!             Reads from FILE or stdin if omitted
 //! ```
 //!
 //! ## Subcommand decrypt
@@ -90,25 +104,37 @@
 //!     sq decrypt [FLAGS] [OPTIONS] [--] [FILE]
 //!
 //! FLAGS:
-//!         --dump                Print a packet dump to stderr
-//!         --dump-session-key    Prints the session key to stderr
-//!     -h, --help                Prints help information
-//!     -x, --hex                 Print a hexdump (implies --dump)
+//!         --dump
+//!             Prints a packet dump to stderr
+//!
+//!         --dump-session-key
+//!             Prints the session key to stderr
+//!
+//!     -h, --help
+//!             Prints help information
+//!
+//!     -x, --hex
+//!             Prints a hexdump (implies --dump)
+//!
 //!
 //! OPTIONS:
-//!     -o, --output <FILE>             Sets the output file to use
+//!     -o, --output <FILE>
+//!             Writes to FILE or stdout if omitted
+//!
 //!         --recipient-key <KEY>...
-//!             Secret key to decrypt with, given as a file (can be given multiple
-//!             times)
+//!             Decrypts with KEY
+//!
 //!         --signer-cert <CERT>...
-//!             The sender's certificate to verify signatures with, given as a file
-//!             (can be given multiple times)
-//!     -n, --signatures <N>
-//!             The number of valid signatures required.  Default: 0
+//!             Verifies signatures with CERT
 //!
+//!     -n, --signatures <N>
+//!             Sets the threshold of valid signatures to N. If this threshold is
+//!             not reached, the message will not be considered verified. [default:
+//!             0]
 //!
 //! ARGS:
-//!     <FILE>    Sets the input file to use
+//!     <FILE>
+//!             Reads from FILE or stdin if omitted
 //! ```
 //!
 //! ## Subcommand sign
@@ -120,23 +146,21 @@
 //!     sq sign [FLAGS] [OPTIONS] [--] [FILE]
 //!
 //! FLAGS:
-//!     -a, --append      Append signature to existing signature
-//!     -B, --binary      Emit binary data
-//!         --detached    Create a detached signature
+//!     -a, --append      Appends a signature to existing signature
+//!     -B, --binary      Emits binary data
+//!         --detached    Creates a detached signature
 //!     -h, --help        Prints help information
 //!     -n, --notarize    Signs a message and all existing signatures
 //!
 //! OPTIONS:
-//!     -o, --output <FILE>          Sets the output file to use
-//!         --signer-key <KEY>...
-//!             Secret key to sign with, given as a file (can be given multiple
-//!             times)
+//!     -o, --output <FILE>          Writes to FILE or stdout if omitted
+//!         --signer-key <KEY>...    Signs using KEY
 //!     -t, --time <TIME>
 //!             Chooses keys valid at the specified time and sets the signature's
 //!             creation time
 //!
 //! ARGS:
-//!     <FILE>    Sets the input file to use
+//!     <FILE>    Reads from FILE or stdin if omitted
 //! ```
 //!
 //! ## Subcommand verify
@@ -148,20 +172,28 @@
 //!     sq verify [OPTIONS] [--] [FILE]
 //!
 //! FLAGS:
-//!     -h, --help    Prints help information
+//!     -h, --help
+//!             Prints help information
+//!
 //!
 //! OPTIONS:
-//!         --detached <SIG>           Verifies a detached signature
-//!     -o, --output <FILE>            Sets the output file to use
+//!         --detached <SIG>
+//!             Verifies a detached signature
+//!
+//!     -o, --output <FILE>
+//!             Writes to FILE or stdout if omitted
+//!
 //!         --signer-cert <CERT>...
-//!             The sender's certificate to verify signatures with, given as a file
-//!             (can be given multiple times)
-//!     -n, --signatures <N>
-//!             The number of valid signatures required.  Default: 0
+//!             Verifies signatures with CERT
 //!
+//!     -n, --signatures <N>
+//!             Sets the threshold of valid signatures to N. If this threshold is
+//!             not reached, the message will not be considered verified. [default:
+//!             0]
 //!
 //! ARGS:
-//!     <FILE>    Sets the input file to use
+//!     <FILE>
+//!             Reads from FILE or stdin if omitted
 //! ```
 //!
 //! ## Subcommand merge-signatures
@@ -176,17 +208,17 @@
 //!     -h, --help    Prints help information
 //!
 //! OPTIONS:
-//!     -o, --output <FILE>    Sets the output file to use
+//!     -o, --output <FILE>    Writes to FILE or stdout if omitted
 //!
 //! ARGS:
-//!     <FILE>    Sets the first input file to use
-//!     <FILE>    Sets the second input file to use
+//!     <FILE>    Reads first message from FILE
+//!     <FILE>    Reads second message from FILE
 //! ```
 //!
 //! ## Subcommand key
 //!
 //! ```text
-//! Manipulates keys
+//! Manages keys
 //!
 //! USAGE:
 //!     sq key <SUBCOMMAND>
@@ -195,40 +227,66 @@
 //!     -h, --help    Prints help information
 //!
 //! SUBCOMMANDS:
-//!     adopt                    Bind keys from one certificate to another.
+//!     generate                 Generates a new key
 //!     attest-certifications
 //!             Attests third-party certifications allowing for their distribution
 //!
-//!     generate                 Generates a new key
+//!     adopt                    Binds keys from one certificate to another
 //!     help
 //!             Prints this message or the help of the given subcommand(s)
 //! ```
 //!
-//! ### Subcommand key adopt
+//! ### Subcommand key generate
 //!
 //! ```text
-//! Bind keys from one certificate to another.
+//! Generates a new key
 //!
 //! USAGE:
-//!     sq key adopt [FLAGS] [OPTIONS] <CERT> --key <KEY>...
+//!     sq key generate [FLAGS] [OPTIONS] --export <OUTFILE>
 //!
 //! FLAGS:
-//!         --allow-broken-crypto
-//!             Allows adopting keys from certificates using broken cryptography.
+//!         --can-sign
+//!             Adds a signing-capable subkey (default)
 //!
-//!     -h, --help                   Prints help information
-//!     -V, --version                Prints version information
+//!         --cannot-encrypt
+//!             Adds no encryption-capable subkey
 //!
-//! OPTIONS:
-//!     -k, --key <KEY>...
-//!             Adds the specified key or subkey to the certificate.
+//!         --cannot-sign
+//!             Adds no signing-capable subkey
 //!
-//!     -r, --keyring <KEYRING>...
-//!             A keyring containing the keys specified in --key.
+//!     -h, --help
+//!             Prints help information
 //!
+//!     -V, --version
+//!             Prints version information
 //!
-//! ARGS:
-//!     <CERT>    The certificate to add keys to.
+//!         --with-password
+//!             Protects the key with a password
+//!
+//!
+//! OPTIONS:
+//!         --can-encrypt <PURPOSE>
+//!             Adds an encryption-capable subkey. Encryption-capable subkeys can be
+//!             marked as suitable for transport encryption, storage encryption, or
+//!             both. [default: universal] [possible values: transport, storage,
+//!             universal]
+//!     -c, --cipher-suite <CIPHER-SUITE>
+//!             Selects the cryptographic algorithms for the key [default: cv25519]
+//!             [possible values: rsa3k, rsa4k, cv25519]
+//!         --expires <TIME>
+//!             Makes the key expire at TIME (as ISO 8601). Use 'never' to create
+//!             keys that do not expire.
+//!         --expires-in <DURATION>
+//!             Makes the key expire after DURATION. Either 'N[ymwd]', for N years,
+//!             months, weeks, or days, or 'never'.
+//!     -e, --export <OUTFILE>
+//!             Writes the key to OUTFILE
+//!
+//!         --rev-cert <FILE or ->
+//!             Writes the revocation certificate to FILE. mandatory if OUTFILE is
+//!             '-'. [default: <OUTFILE>.rev]
+//!     -u, --userid <EMAIL>...
+//!             Adds a userid to the key
 //! ```
 //!
 //! ### Subcommand key attest-certifications
@@ -240,59 +298,42 @@
 //!     sq key attest-certifications [FLAGS] <KEY>
 //!
 //! FLAGS:
-//!         --all        Attest to all certifications
+//!         --all        Attests to all certifications
 //!     -h, --help       Prints help information
-//!         --none       Remove all prior attestations
+//!         --none       Removes all prior attestations
 //!     -V, --version    Prints version information
 //!
 //! ARGS:
-//!     <KEY>    Change attestations on this key.
+//!     <KEY>    Changes attestations on KEY
 //! ```
 //!
-//! ### Subcommand key generate
+//! ### Subcommand key adopt
 //!
 //! ```text
-//! Generates a new key
+//! Binds keys from one certificate to another
 //!
 //! USAGE:
-//!     sq key generate [FLAGS] [OPTIONS] --export <OUTFILE>
+//!     sq key adopt [FLAGS] [OPTIONS] <TARGET-KEY> --key <KEY>...
 //!
 //! FLAGS:
-//!         --can-sign          The key has a signing-capable subkey (default)
-//!         --cannot-encrypt    The key will not be able to encrypt data
-//!         --cannot-sign       The key will not be able to sign data
-//!     -h, --help              Prints help information
-//!     -V, --version           Prints version information
-//!         --with-password     Prompt for a password to protect the generated key
-//!                             with.
+//!         --allow-broken-crypto
+//!             Allows adopting keys from certificates using broken cryptography
 //!
-//! OPTIONS:
-//!         --can-encrypt <PURPOSE>
-//!             The key has an encryption-capable subkey (default: universal)
-//!             [possible values: transport, storage, universal]
-//!     -c, --cipher-suite <CIPHER-SUITE>
-//!             Cryptographic algorithms used for the key. [default: cv25519]
-//!             [possible values: rsa3k, rsa4k, cv25519]
-//!         --expires <TIME>
-//!             Absolute time when the key should expire, or 'never'.
+//!     -h, --help                   Prints help information
+//!     -V, --version                Prints version information
 //!
-//!         --expires-in <DURATION>
-//!             Relative time when the key should expire.  Either 'N[ymwd]', for N
-//!             years, months, weeks, or days, or 'never'.
-//!     -e, --export <OUTFILE>
-//!             Exports the key instead of saving it in the store
+//! OPTIONS:
+//!     -k, --key <KEY>...             Adds the key or subkey KEY to the TARGET-KEY
+//!     -r, --keyring <KEY-RING>...    Supplies keys for use in --key.
 //!
-//!         --rev-cert <FILE or ->
-//!             Sets the output file for the revocation certificate. Default is
-//!             <OUTFILE>.rev, mandatory if OUTFILE is '-'.
-//!     -u, --userid <EMAIL>...
-//!             Add userid to the key (can be given multiple times)
+//! ARGS:
+//!     <TARGET-KEY>    Adds keys to TARGET-KEY
 //! ```
 //!
 //! ## Subcommand certring
 //!
 //! ```text
-//! Manipulates certificate rings
+//! Manages collections of certificates (also known as 'keyrings)'.
 //!
 //! USAGE:
 //!     sq certring <SUBCOMMAND>
@@ -313,44 +354,32 @@
 //! ### Subcommand certring filter
 //!
 //! ```text
-//! If multiple predicates are given, they are or'ed, i.e. a certificate matches if
-//! any of the predicates match.  To require all predicates to match, chain multiple
-//! invocations of this command.
+//! Joins certs into a certring applying a filter
 //!
 //! USAGE:
 //!     sq certring filter [FLAGS] [OPTIONS] [--] [FILE]...
 //!
 //! FLAGS:
-//!     -B, --binary
-//!             Emit binary data
-//!
-//!     -h, --help
-//!             Prints help information
-//!
-//!     -P, --prune-certs
-//!             Remove certificate components not matching the filter
-//!
-//!     -V, --version
-//!             Prints version information
-//!
+//!     -B, --binary         Emits binary data
+//!     -h, --help           Prints help information
+//!     -P, --prune-certs    Removes certificate components not matching the filter
+//!     -V, --version        Prints version information
 //!
 //! OPTIONS:
-//!         --domain <FQDN>...
-//!             Match on this email domain name
-//!
-//!         --email <ADDRESS>...
-//!             Match on this email address
+//!         --domain <FQDN>...      Matches on email domain FQDN
+//!         --email <ADDRESS>...    Matches on email ADDRESS
+//!         --name <NAME>...        Matches on NAME
+//!     -o, --output <FILE>         Writes to FILE or stdout if omitted
 //!
-//!         --name <NAME>...
-//!             Match on this name
-//!
-//!     -o, --output <FILE>
-//!             Sets the output file to use
+//! ARGS:
+//!     <FILE>...    Reads from FILE or stdin if omitted
 //!
+//! If multiple predicates are given, they are or'ed, i.e. a certificate matches if
+//! any of the predicates match.  To require all predicates to match, chain multiple
+//! invocations of this command:
 //!
-//! ARGS:
-//!     <FILE>...
-//!             Sets the input files to use
+//! $ cat certs.pgp | sq certring filter --domain example.org | sq certring filter
+//! --name Juliett
 //! ```
 //!
 //! ### Subcommand certring join
@@ -362,15 +391,15 @@
 //!     sq certring join [FLAGS] [OPTIONS] [FILE]...
 //!
 //! FLAGS:
-//!     -B, --binary     Emit binary data
+//!     -B, --binary     Emits binary data
 //!     -h, --help       Prints help information
 //!     -V, --version    Prints version information
 //!
 //! OPTIONS:
-//!     -o, --output <FILE>    Sets the output file to use
+//!     -o, --output <FILE>    Writes to FILE or stdout if omitted
 //!
 //! ARGS:
-//!     <FILE>...    Sets the input files to use
+//!     <FILE>...    Reads from FILE
 //! ```
 //!
 //! ### Subcommand certring list
@@ -386,7 +415,7 @@
 //!     -V, --version    Prints version information
 //!
 //! ARGS:
-//!     <FILE>    Sets the input file to use
+//!     <FILE>    Reads from FILE or stdin if omitted
 //! ```
 //!
 //! ### Subcommand certring split
@@ -402,48 +431,51 @@
 //!     -V, --version    Prints version information
 //!
 //! OPTIONS:
-//!     -p, --prefix <FILE>    Sets the prefix to use for output files (defaults to
-//!                            the input filename with a dash, or 'output' if
-//!                            certring is read from stdin)
+//!     -p, --prefix <FILE>    Writes to files with prefix FILE [defaults to the
+//!                            input filename with a dash, or 'output' if certring
+//!                            is read from stdin]
 //!
 //! ARGS:
-//!     <FILE>    Sets the input file to use
+//!     <FILE>    Reads from FILE or stdin if omitted
 //! ```
 //!
 //! ## Subcommand certify
 //!
 //! ```text
-//! Certify a User ID for a Certificate
+//! Certifies a User ID for a Certificate
 //!
 //! USAGE:
-//!     sq certify [FLAGS] [OPTIONS] <CERTIFIER> <CERTIFICATE> <USERID>
+//!     sq certify [FLAGS] [OPTIONS] <CERTIFIER-KEY> <CERTIFICATE> <USERID>
 //!
 //! FLAGS:
-//!     -h, --help             Prints help information
-//!     -l, --local            Makes the certification a local certification.
-//!                            Normally, local certifications are not exported.
-//!         --non-revocable    Marks the certification as being non-revocable. That
-//!                            is, you cannot later revoke this certification.  This
-//!                            should normally only be used with an expiration.
+//!     -h, --help
+//!             Prints help information
+//!
+//!     -l, --local
+//!             Makes the certification a local certification.  Normally, local
+//!             certifications are not exported.
+//!         --non-revocable
+//!             Marks the certification as being non-revocable. That is, you cannot
+//!             later revoke this certification.  This should normally only be used
+//!             with an expiration.
 //!
 //! OPTIONS:
 //!     -a, --amount <TRUST_AMOUNT>
-//!             The amount of trust.  Values between 1 and 120 are meaningful. 120
-//!             means fully trusted.  Values less than 120 indicate the degree of
-//!             trust.  60 is usually used for partially trusted.  The default is
+//!             Sets the amount of trust.  Values between 1 and 120 are meaningful.
+//!             120 means fully trusted.  Values less than 120 indicate the degree
+//!             of trust.  60 is usually used for partially trusted.  The default is
 //!             120.
 //!     -d, --depth <TRUST_DEPTH>
-//!             The trust depth (sometimes referred to as the trust level).  0 means
-//!             a normal certification of <CERTIFICATE, USERID>.  1 means
+//!             Sets the trust depth (sometimes referred to as the trust level).  0
+//!             means a normal certification of <CERTIFICATE, USERID>.  1 means
 //!             CERTIFICATE is also a trusted introducer, 2 means CERTIFICATE is a
 //!             meta-trusted introducer, etc.  The default is 0.
 //!         --expires <TIME>
-//!             Absolute time when the certification should expire, or 'never'.
-//!
+//!             Makes the certification expire at TIME (as ISO 8601). Use 'never' to
+//!             create certifications that do not expire.
 //!         --expires-in <DURATION>
-//!             Relative time when the certification should expire.  Either
-//!             'N[ymwd]', for N years, months, weeks, or days, or 'never'.  The
-//!             default is 5 years.
+//!             Makes the certification expire after DURATION. Either 'N[ymwd]', for
+//!             N years, months, weeks, or days, or 'never'.  [default: 5y]
 //!     -r, --regex <REGEX>...
 //!             Adds a regular expression to constrain what a trusted introducer can
 //!             certify.  The regular expression must match the certified User ID in
@@ -452,15 +484,20 @@
 //!             least one must match.
 //!
 //! ARGS:
-//!     <CERTIFIER>      The key to certify the certificate.
-//!     <CERTIFICATE>    The certificate to certify.
-//!     <USERID>         The User ID to certify.
+//!     <CERTIFIER-KEY>
+//!             Creates the certificate using CERTIFIER-KEY.
+//!
+//!     <CERTIFICATE>
+//!             Certifies CERTIFICATE.
+//!
+//!     <USERID>
+//!             Certifies USERID for CERTIFICATE.
 //! ```
 //!
 //! ## Subcommand autocrypt
 //!
 //! ```text
-//! Autocrypt support
+//! Communicates certificates using Autocrypt
 //!
 //! USAGE:
 //!     sq autocrypt <SUBCOMMAND>
@@ -469,7 +506,7 @@
 //!     -h, --help    Prints help information
 //!
 //! SUBCOMMANDS:
-//!     decode           Converts Autocrypt-encoded keys to OpenPGP Certificates
+//!     decode           Reads Autocrypt-encoded certificates
 //!     encode-sender    Encodes the sender's OpenPGP Certificates into an
 //!                      Autocrypt header
 //!     help             Prints this message or the help of the given
@@ -479,7 +516,7 @@
 //! ### Subcommand autocrypt decode
 //!
 //! ```text
-//! Converts Autocrypt-encoded keys to OpenPGP Certificates
+//! Reads Autocrypt-encoded certificates
 //!
 //! USAGE:
 //!     sq autocrypt decode [OPTIONS] [FILE]
@@ -489,10 +526,10 @@
 //!     -V, --version    Prints version information
 //!
 //! OPTIONS:
-//!     -o, --output <FILE>    Sets the output file to use
+//!     -o, --output <FILE>    Writes to FILE or stdout if omitted
 //!
 //! ARGS:
-//!     <FILE>    Sets the input file to use
+//!     <FILE>    Reads from FILE or stdin if omitted
 //! ```
 //!
 //! ### Subcommand autocrypt encode-sender
@@ -508,16 +545,16 @@
 //!     -V, --version    Prints version information
 //!
 //! OPTIONS:
-//!         --address <address>
-//!             Select userid to use.  [default: primary userid]
+//!         --email <ADDRESS>
+//!             Sets the address [default: primary userid]
 //!
-//!     -o, --output <FILE>                      Sets the output file to use
+//!     -o, --output <FILE>                      Writes to FILE or stdout if omitted
 //!         --prefer-encrypt <prefer-encrypt>
 //!             Sets the prefer-encrypt attribute [default: nopreference]  [possible
 //!             values: nopreference, mutual]
 //!
 //! ARGS:
-//!     <FILE>    Sets the input file to use
+//!     <FILE>    Reads from FILE or stdin if omitted
 //! ```
 //!
 //! ## Subcommand keyserver
@@ -552,16 +589,16 @@
 //!     sq keyserver get [FLAGS] [OPTIONS] <QUERY>
 //!
 //! FLAGS:
-//!     -B, --binary     Emit binary data
+//!     -B, --binary     Emits binary data
 //!     -h, --help       Prints help information
 //!     -V, --version    Prints version information
 //!
 //! OPTIONS:
-//!     -o, --output <FILE>    Sets the output file to use
+//!     -o, --output <FILE>    Writes to FILE or stdout if omitted
 //!
 //! ARGS:
-//!     <QUERY>    Fingerprint, KeyID, or email address of the cert(s) to
-//!                retrieve
+//!     <QUERY>    Retrieve certificate(s) using QUERY. This may be a
+//!                fingerprint, a KeyID, or an email address.
 //! ```
 //!
 //! ### Subcommand keyserver send
@@ -577,7 +614,7 @@
 //!     -V, --version    Prints version information
 //!
 //! ARGS:
-//!     <FILE>    Sets the input file to use
+//!     <FILE>    Reads from FILE or stdin if omitted
 //! ```
 //!
 //! ## Subcommand wkd
@@ -600,8 +637,7 @@
 //!     generate    Generates a Web Key Directory for the given domain and keys.
 //!                 If the WKD exists, the new keys will be inserted and it is
 //!                 updated and existing ones will be updated.
-//!     get         Writes to the standard output the Cert retrieved from a Web
-//!                 Key Directory, given an email address
+//!     get         Queries for certs using Web Key Directory
 //!     help        Prints this message or the help of the given subcommand(s)
 //!     url         Prints the Web Key Directory URL of an email address.
 //! ```
@@ -614,38 +650,45 @@
 //! updated.
 //!
 //! USAGE:
-//!     sq wkd generate [FLAGS] <WEB-ROOT> <DOMAIN> [KEYRING]
+//!     sq wkd generate [FLAGS] <WEB-ROOT> <FQDN> [CERT-RING]
 //!
 //! FLAGS:
-//!     -d, --direct_method    Use the direct method. [default: advanced method]
-//!     -h, --help             Prints help information
-//!     -V, --version          Prints version information
+//!     -d, --direct-method
+//!             Uses the direct method [default: advanced method]
+//!
+//!     -h, --help
+//!             Prints help information
+//!
+//!     -V, --version
+//!             Prints version information
+//!
 //!
 //! ARGS:
-//!     <WEB-ROOT>    The location to write the WKD to. This must be the
-//!                   directory the webserver is serving the '.well-known'
-//!                   directory from.
-//!     <DOMAIN>      The domain for the WKD.
-//!     <KEYRING>     The keyring file with the keys to add to the WKD.
+//!     <WEB-ROOT>
+//!             Writes the WKD to WEB-ROOT. Transfer this directory to the
+//!             webserver.
+//!     <FQDN>
+//!             Generates a WKD for FQDN
+//!
+//!     <CERT-RING>
+//!             Adds certificates from CERT-RING to the WKD
 //! ```
 //!
 //! ### Subcommand wkd get
 //!
 //! ```text
-//! Writes to the standard output the Cert retrieved from a Web Key Directory, given
-//! an email address
+//! Queries for certs using Web Key Directory
 //!
 //! USAGE:
-//!     sq wkd get [FLAGS] <EMAIL_ADDRESS>
+//!     sq wkd get [FLAGS] <ADDRESS>
 //!
 //! FLAGS:
-//!     -B, --binary     Emit binary data
+//!     -B, --binary     Emits binary data
 //!     -h, --help       Prints help information
 //!     -V, --version    Prints version information
 //!
 //! ARGS:
-//!     <EMAIL_ADDRESS>    The email address from which to obtain the Cert from
-//!                        a WKD.
+//!     <ADDRESS>    Queries a cert for ADDRESS
 //! ```
 //!
 //! ### Subcommand wkd url
@@ -654,20 +697,20 @@
 //! Prints the Web Key Directory URL of an email address.
 //!
 //! USAGE:
-//!     sq wkd url <EMAIL_ADDRESS>
+//!     sq wkd url <ADDRESS>
 //!
 //! FLAGS:
 //!     -h, --help