path: root/sq/src/sq-usage.rs

//! A command-line frontend for Sequoia.
//!
//! # Usage
//!
//! ```text
//! Sequoia is an implementation of OpenPGP.  This is a command-line frontend.
//!
//! USAGE:
//!     sq [FLAGS] [OPTIONS] <SUBCOMMAND>
//!
//! FLAGS:
//!     -f, --force      Overwrite 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.
//!     -p, --policy <NETWORK-POLICY>         Sets the network policy to use
//!
//! SUBCOMMANDS:
//!     encrypt             Encrypts a message
//!     decrypt             Decrypts an OpenPGP message
//!     sign                Signs a message
//!     verify              Verifies a message
//!     merge-signatures    Merges two signatures
//!     key                 Manipulates keys
//!     certring            Manipulates certificate rings
//!     autocrypt           Autocrypt support
//!     keyserver           Interacts with keyservers
//!     wkd                 Interacts with Web Key Directories
//!     armor               Applies ASCII Armor to a file
//!     dearmor             Removes ASCII Armor from a file
//!     inspect             Inspects a sequence of OpenPGP packets
//!     packet              OpenPGP Packet manipulation
//!     certify             Certify a User ID for a Certificate
//!     help                Prints this message or the help of the given
//!                         subcommand(s)
//! ```
//!
//! ## Subcommand encrypt
//!
//! ```text
//! Encrypts a message
//!
//! USAGE:
//!     sq encrypt [FLAGS] [OPTIONS] [--] [FILE]
//!
//! FLAGS:
//!     -B, --binary                Don't ASCII-armor encode the OpenPGP 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
//!
//! OPTIONS:
//!         --compression <KIND>
//!             Selects compression scheme to use [default: pad]  [possible values:
//!             none, pad, zip, zlib, bzip2]
//!         --mode <MODE>
//!             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:
//!             transport, rest, all]
//!     -o, --output <FILE>                    Sets the output file to use
//!         --recipient-cert <CERT-RING>...
//!             Recipients to encrypt for, given as a file (can be given multiple
//!             times)
//!         --signer-key <KEY>...
//!             Secret key to sign with, given as a file (can be given multiple
//!             times)
//!     -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
//! ```
//!
//! ## Subcommand decrypt
//!
//! ```text
//! Decrypts an OpenPGP message
//!
//! USAGE:
//!     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)
//!
//! OPTIONS:
//!     -o, --output <FILE>             Sets the output file to use
//!         --recipient-key <KEY>...
//!             Secret key to decrypt with, given as a file (can be given multiple
//!             times)
//!         --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
//!
//!
//! ARGS:
//!     <FILE>    Sets the input file to use
//! ```
//!
//! ## Subcommand sign
//!
//! ```text
//! Signs a message
//!
//! USAGE:
//!     sq sign [FLAGS] [OPTIONS] [--] [FILE]
//!
//! FLAGS:
//!     -a, --append      Append signature to existing signature
//!     -B, --binary      Don't ASCII-armor encode the OpenPGP data
//!         --detached    Create 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)
//!     -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
//! ```
//!
//! ## Subcommand verify
//!
//! ```text
//! Verifies a message
//!
//! USAGE:
//!     sq verify [OPTIONS] [--] [FILE]
//!
//! FLAGS:
//!     -h, --help    Prints help information
//!
//! OPTIONS:
//!         --detached <SIG>           Verifies a detached signature
//!     -o, --output <FILE>            Sets the output file to use
//!         --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
//!
//!
//! ARGS:
//!     <FILE>    Sets the input file to use
//! ```
//!
//! ## Subcommand merge-signatures
//!
//! ```text
//! Merges two signatures
//!
//! USAGE:
//!     sq merge-signatures [OPTIONS] [ARGS]
//!
//! FLAGS:
//!     -h, --help    Prints help information
//!
//! OPTIONS:
//!     -o, --output <FILE>    Sets the output file to use
//!
//! ARGS:
//!     <FILE>    Sets the first input file to use
//!     <FILE>    Sets the second input file to use
//! ```
//!
//! ## Subcommand key
//!
//! ```text
//! Manipulates keys
//!
//! USAGE:
//!     sq key <SUBCOMMAND>
//!
//! FLAGS:
//!     -h, --help    Prints help information
//!
//! SUBCOMMANDS:
//!     adopt                    Bind keys from one certificate to another.
//!     attest-certifications
//!             Attests third-party certifications allowing for their distribution
//!
//!     generate                 Generates a new key
//!     help
//!             Prints this message or the help of the given subcommand(s)
//! ```
//!
//! ### Subcommand key adopt
//!
//! ```text
//! Bind keys from one certificate to another.
//!
//! USAGE:
//!     sq key adopt [FLAGS] [OPTIONS] <CERT> --key <KEY>...
//!
//! FLAGS:
//!         --allow-broken-crypto
//!             Allows adopting keys from certificates using broken cryptography.
//!
//!     -h, --help                   Prints help information
//!     -V, --version                Prints version information
//!
//! OPTIONS:
//!     -k, --key <KEY>...
//!             Adds the specified key or subkey to the certificate.
//!
//!     -r, --keyring <KEYRING>...
//!             A keyring containing the keys specified in --key.
//!
//!
//! ARGS:
//!     <CERT>    The certificate to add keys to.
//! ```
//!
//! ### Subcommand key attest-certifications
//!
//! ```text
//! Attests third-party certifications allowing for their distribution
//!
//! USAGE:
//!     sq key attest-certifications [FLAGS] <KEY>
//!
//! FLAGS:
//!         --all        Attest to all certifications
//!     -h, --help       Prints help information
//!         --none       Remove all prior attestations
//!     -V, --version    Prints version information
//!
//! ARGS:
//!     <KEY>    Change attestations on this key.
//! ```
//!
//! ### Subcommand key generate
//!
//! ```text
//! Generates a new key
//!
//! USAGE:
//!     sq key generate [FLAGS] [OPTIONS] --export <OUTFILE>
//!
//! 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.
//!
//! 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'.
//!
//!         --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
//!
//!         --rev-cert <FILE or ->