File: gnupg.info,  Node: Operational GPG Commands,  Next: OpenPGP Key Management,  Prev: General GPG Commands,  Up: GPG Commands

4.1.2 Commands to select the type of operation
----------------------------------------------

'--sign'
'-s'
     Sign a message.  This command may be combined with '--encrypt' (to
     sign and encrypt a message), '--symmetric' (to sign and
     symmetrically encrypt a message), or both '--encrypt' and
     '--symmetric' (to sign and encrypt a message that can be decrypted
     using a secret key or a passphrase).  The signing key is chosen by
     default or can be set explicitly using the '--local-user' and
     '--default-key' options.

'--clear-sign'
'--clearsign'
     Make a cleartext signature.  The content in a cleartext signature
     is readable without any special software.  OpenPGP software is only
     needed to verify the signature.  cleartext signatures may modify
     end-of-line whitespace for platform independence and are not
     intended to be reversible.  The signing key is chosen by default or
     can be set explicitly using the '--local-user' and '--default-key'
     options.

'--detach-sign'
'-b'
     Make a detached signature.

'--encrypt'
'-e'
     Encrypt data to one or more public keys.  This command may be
     combined with '--sign' (to sign and encrypt a message),
     '--symmetric' (to encrypt a message that can be decrypted using a
     secret key or a passphrase), or '--sign' and '--symmetric' together
     (for a signed message that can be decrypted using a secret key or a
     passphrase).  '--recipient' and related options specify which
     public keys to use for encryption.

'--symmetric'
'-c'
     Encrypt with a symmetric cipher using a passphrase.  The default
     symmetric cipher used is AES-128, but may be chosen with the
     '--cipher-algo' option.  This command may be combined with '--sign'
     (for a signed and symmetrically encrypted message), '--encrypt'
     (for a message that may be decrypted via a secret key or a
     passphrase), or '--sign' and '--encrypt' together (for a signed
     message that may be decrypted via a secret key or a passphrase).
     'gpg' caches the passphrase used for symmetric encryption so that a
     decrypt operation may not require that the user needs to enter the
     passphrase.  The option '--no-symkey-cache' can be used to disable
     this feature.

'--store'
     Store only (make a simple literal data packet).

'--decrypt'
'-d'
     Decrypt the file given on the command line (or STDIN if no file is
     specified) and write it to STDOUT (or the file specified with
     '--output').  If the decrypted file is signed, the signature is
     also verified.  This command differs from the default operation, as
     it never writes to the filename which is included in the file and
     it rejects files that don't begin with an encrypted message.

'--verify'
     Assume that the first argument is a signed file and verify it
     without generating any output.  With no arguments, the signature
     packet is read from STDIN. If only one argument is given, the
     specified file is expected to include a complete signature.

     With more than one argument, the first argument should specify a
     file with a detached signature and the remaining files should
     contain the signed data.  To read the signed data from STDIN, use
     '-' as the second filename.  For security reasons, a detached
     signature will not read the signed material from STDIN if not
     explicitly specified.

     Note: If the option '--batch' is not used, 'gpg' may assume that a
     single argument is a file with a detached signature, and it will
     try to find a matching data file by stripping certain suffixes.
     Using this historical feature to verify a detached signature is
     strongly discouraged; you should always specify the data file
     explicitly.

     Note: When verifying a cleartext signature, 'gpg' verifies only
     what makes up the cleartext signed data and not any extra data
     outside of the cleartext signature or the header lines directly
     following the dash marker line.  The option '--output' may be used
     to write out the actual signed data, but there are other pitfalls
     with this format as well.  It is suggested to avoid cleartext
     signatures in favor of detached signatures.

     Note: With option '--batch' he verification of signatures stops at
     the first bad signature.  This is a safe default for unattended
     processing but sometimes a status for all signatures is needed.  To
     override this early bailout use the option '--proc-all-sigs'.

     Note: To check whether a file was signed by a certain key the
     option '--assert-signer' can be used.  As an alternative the 'gpgv'
     tool can be used.  'gpgv' is designed to compare signed data
     against a list of trusted keys and returns with success only for a
     good signature.  It has its own manual page.

'--multifile'
     This modifies certain other commands to accept multiple files for
     processing on the command line or read from STDIN with each
     filename on a separate line.  This allows for many files to be
     processed at once.  '--multifile' may currently be used along with
     '--verify', '--encrypt', and '--decrypt'.  Note that '--multifile
     --verify' may not be used with detached signatures.

'--verify-files'
     Identical to '--multifile --verify'.

'--encrypt-files'
     Identical to '--multifile --encrypt'.

'--decrypt-files'
     Identical to '--multifile --decrypt'.

'--list-keys'
'-k'
'--list-public-keys'
     List the specified keys.  If no keys are specified, then all keys
     from the configured public keyrings are listed.

     Never use the output of this command in scripts or other programs.
     The output is intended only for humans and its format is likely to
     change.  The '--with-colons' option emits the output in a stable,
     machine-parseable format, which is intended for use by scripts and
     other programs.

'--list-secret-keys'
'-K'
     List the specified secret keys.  If no keys are specified, then all
     known secret keys are listed.  A '#' after the initial tags 'sec'
     or 'ssb' means that the secret key or subkey is currently not
     usable.  We also say that this key has been taken offline (for
     example, a primary key can be taken offline by exporting the key
     using the command '--export-secret-subkeys').  A '>' after these
     tags indicate that the key is stored on a smartcard.  See also
     '--list-keys'.

'--check-signatures'
'--check-sigs'
     Same as '--list-keys', but the key signatures are verified and
     listed too.  Note that for performance reasons the revocation
     status of a signing key is not shown.  This command has the same
     effect as using '--list-keys' with '--with-sig-check'.

     The status of the verification is indicated by a flag directly
     following the "sig" tag (and thus before the flags described below.
     A "!"  indicates that the signature has been successfully verified,
     a "-" denotes a bad signature and a "%" is used if an error
     occurred while checking the signature (e.g.  a non supported
     algorithm).  Signatures where the public key is not available are
     not listed; to see their keyids the command '--list-sigs' can be
     used.

     For each signature listed, there are several flags in between the
     signature status flag and keyid.  These flags give additional
     information about each key signature.  From left to right, they are
     the numbers 1-3 for certificate check level (see
     '--ask-cert-level'), "L" for a local or non-exportable signature
     (see '--lsign-key'), "R" for a nonRevocable signature (see the
     '--edit-key' command "nrsign"), "P" for a signature that contains a
     policy URL (see '--cert-policy-url'), "N" for a signature that
     contains a notation (see '--cert-notation'), "X" for an eXpired
     signature (see '--ask-cert-expire'), and the numbers 1-9 or "T" for
     10 and above to indicate trust signature levels (see the
     '--edit-key' command "tsign").

'--locate-keys'
'--locate-external-keys'
     Locate the keys given as arguments.  This command basically uses
     the same algorithm as used when locating keys for encryption and
     may thus be used to see what keys 'gpg' might use.  In particular
     external methods as defined by '--auto-key-locate' are used to
     locate a key if the arguments comain valid mail addresses.  Only
     public keys are listed.

     The variant '--locate-external-keys' does not consider a locally
     existing key and can thus be used to force the refresh of a key via
     the defined external methods.  If a fingerprint is given and and
     the methods defined by -auto-key-locate define LDAP servers, the
     key is fetched from these resources; defined non-LDAP keyservers
     are skipped.

'--show-keys'
     This commands takes OpenPGP keys as input and prints information
     about them in the same way the command '--list-keys' does for
     locally stored key.  In addition the list options
     'show-unusable-uids', 'show-unusable-subkeys', 'show-notations' and
     'show-policy-urls' are also enabled.  As usual for automated
     processing, this command should be combined with the option
     '--with-colons'.

'--fingerprint'
     List all keys (or the specified ones) along with their
     fingerprints.  This is the same output as '--list-keys' but with
     the additional output of a line with the fingerprint.  May also be
     combined with '--check-signatures'.  If this command is given
     twice, the fingerprints of all secondary keys are listed too.  This
     command also forces pretty printing of fingerprints if the keyid
     format has been set to "none".

'--list-packets'
     List only the sequence of packets.  This command is only useful for
     debugging.  When used with option '--verbose' the actual MPI values
     are dumped and not only their lengths.  Note that the output of
     this command may change with new releases.

'--edit-card'
'--card-edit'
     Present a menu to work with a smartcard.  The subcommand "help"
     provides an overview on available commands.  For a detailed
     description, please see the Card HOWTO at
     https://gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
     Please note that the command "openpgp" can be used to switch to the
     OpenPGP application of cards which by default are presenting
     another application (e.g.  PIV).

'--card-status'
     Show the content of the smart card.

'--change-pin'
     Present a menu to allow changing the PIN of a smartcard.  This
     functionality is also available as the subcommand "passwd" with the
     '--edit-card' command.

'--delete-keys NAME'
     Remove key from the public keyring.  In batch mode either '--yes'
     is required or the key must be specified by fingerprint.  This is a
     safeguard against accidental deletion of multiple keys.  If the
     exclamation mark syntax is used with the fingerprint of a subkey
     only that subkey is deleted; if the exclamation mark is used with
     the fingerprint of the primary key the entire public key is
     deleted.

'--delete-secret-keys NAME'
     Remove key from the secret keyring.  In batch mode the key must be
     specified by fingerprint.  The option '--yes' can be used to advise
     gpg-agent not to request a confirmation.  This extra pre-caution is
     done because 'gpg' can't be sure that the secret key (as controlled
     by gpg-agent) is only used for the given OpenPGP public key.  If
     the exclamation mark syntax is used with the fingerprint of a
     subkey only the secret part of that subkey is deleted; if the
     exclamation mark is used with the fingerprint of the primary key
     only the secret part of the primary key is deleted.

'--delete-secret-and-public-key NAME'
     Same as '--delete-key', but if a secret key exists, it will be
     removed first.  In batch mode the key must be specified by
     fingerprint.  The option '--yes' can be used to advise gpg-agent
     not to request a confirmation.

'--export'
     Either export all keys from all keyrings (default keyring and those
     registered via option '--keyring'), or if at least one name is
     given, those of the given name.  The exported keys are written to
     STDOUT or to the file given with option '--output'.  Use together
     with '--armor' to mail those keys.

'--send-keys KEYIDS'
     Similar to '--export' but sends the keys to a keyserver.
     Fingerprints may be used instead of key IDs.  Don't send your
     complete keyring to a keyserver -- select only those keys which are
     new or changed by you.  If no KEYIDS are given, 'gpg' does nothing.

     Take care: Keyservers are by design write only systems and thus it
     is not possible to ever delete keys once they have been send to a
     keyserver.

'--export-secret-keys'
'--export-secret-subkeys'
     Same as '--export', but exports the secret keys instead.  The
     exported keys are written to STDOUT or to the file given with
     option '--output'.  This command is often used along with the
     option '--armor' to allow for easy printing of the key for paper
     backup; however the external tool 'paperkey' does a better job of
     creating backups on paper.  Note that exporting a secret key can be
     a security risk if the exported keys are sent over an insecure
     channel.

     The second form of the command has the special property to render
     the secret part of the primary key useless; this is a GNU extension
     to OpenPGP and other implementations can not be expected to
     successfully import such a key.  Its intended use is in generating
     a full key with an additional signing subkey on a dedicated
     machine.  This command then exports the key without the primary key
     to the main machine.

     GnuPG may ask you to enter the passphrase for the key.  This is
     required, because the internal protection method of the secret key
     is different from the one specified by the OpenPGP protocol.

'--export-ssh-key'
     This command is used to export a key in the OpenSSH public key
     format.  It requires the specification of one key by the usual
     means and exports the latest valid subkey which has an
     authentication capability to STDOUT or to the file given with
     option '--output'.  That output can directly be added to ssh's
     'authorized_key' file.

     By specifying the key to export using a key ID or a fingerprint
     suffixed with an exclamation mark (!), a specific subkey or the
     primary key can be exported.  This does not even require that the
     key has the authentication capability flag set.

'--import'
'--fast-import'
     Import/merge keys.  This adds the given keys to the keyring.  The
     fast version is currently just a synonym.

     There are a few other options which control how this command works.
     Most notable here is the '--import-options merge-only' option which
     does not insert new keys but does only the merging of new
     signatures, user-IDs and subkeys.

'--receive-keys KEYIDS'
'--recv-keys KEYIDS'
     Import the keys with the given KEYIDS from a keyserver.

'--refresh-keys'
     Request updates from a keyserver for keys that already exist on the
     local keyring.  This is useful for updating a key with the latest
     signatures, user IDs, etc.  Calling this with no arguments will
     refresh the entire keyring.

'--search-keys NAMES'
     Search the keyserver for the given NAMES.  Multiple names given
     here will be joined together to create the search string for the
     keyserver.  Note that keyservers search for NAMES in a different
     and simpler way than gpg does.  The best choice is to use a mail
     address.  Due to data privacy reasons keyservers may even not even
     allow searching by user id or mail address and thus may only return
     results when being used with the '--recv-key' command to search by
     key fingerprint or keyid.

'--fetch-keys URIS'
     Retrieve keys located at the specified URIS.  Note that different
     installations of GnuPG may support different protocols (HTTP, FTP,
     LDAP, etc.).  When using HTTPS the system provided root
     certificates are used by this command.

'--update-trustdb'
     Do trust database maintenance.  This command iterates over all keys
     and builds the Web of Trust.  This is an interactive command
     because it may have to ask for the "ownertrust" values for keys.
     The user has to give an estimation of how far she trusts the owner
     of the displayed key to correctly certify (sign) other keys.  GnuPG
     only asks for the ownertrust value if it has not yet been assigned
     to a key.  Using the '--edit-key' menu, the assigned value can be
     changed at any time.

'--check-trustdb'
     Do trust database maintenance without user interaction.  From time
     to time the trust database must be updated so that expired keys or
     signatures and the resulting changes in the Web of Trust can be
     tracked.  Normally, GnuPG will calculate when this is required and
     do it automatically unless '--no-auto-check-trustdb' is set.  This
     command can be used to force a trust database check at any time.
     The processing is identical to that of '--update-trustdb' but it
     skips keys with a not yet defined "ownertrust".

     For use with cron jobs, this command can be used together with
     '--batch' in which case the trust database check is done only if a
     check is needed.  To force a run even in batch mode add the option
     '--yes'.

'--export-ownertrust'
     Send the ownertrust values to STDOUT. This is useful for backup
     purposes as these values are the only ones which can't be
     re-created from a corrupted trustdb.  Example:
            gpg --export-ownertrust > otrust.txt

'--import-ownertrust'
     Update the trustdb with the ownertrust values stored in 'files' (or
     STDIN if not given); existing values will be overwritten.  In case
     of a severely damaged trustdb and if you have a recent backup of
     the ownertrust values (e.g.  in the file 'otrust.txt'), you may
     re-create the trustdb using these commands:
            cd ~/.gnupg
            rm trustdb.gpg
            gpg --import-ownertrust < otrust.txt

'--rebuild-keydb-caches'
     When updating from version 1.0.6 to 1.0.7 this command should be
     used to create signature caches in the keyring.  It might be handy
     in other situations too.

'--print-md ALGO'
'--print-mds'
     Print message digest of algorithm ALGO for all given files or
     STDIN. With the second form (or a deprecated "*" for ALGO) digests
     for all available algorithms are printed.

'--gen-random 0|1|2|16|30 COUNT'
     Emit COUNT random bytes of the given quality level 0, 1 or 2.  If
     COUNT is not given or zero, an endless sequence of random bytes
     will be emitted.  If used with '--armor' the output will be base64
     encoded.  The special level 16 uses a quality level of 1 and
     outputs an endless stream of hex-encoded octets.  The special level
     30 outputs random as 30 zBase-32 characters.

'--gen-prime MODE BITS'
     Use the source, Luke :-).  The output format is subject to change
     with any release.

'--enarmor'
'--dearmor'
     Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
     This is a GnuPG extension to OpenPGP and in general not very
     useful.  The '--dearmor' command can also be used to dearmor PEM
     armors.

'--unwrap'
     This option modifies the command '--decrypt' to output the original
     message with the encryption layer removed.  Thus the output will be
     an OpenPGP data structure which often means a signed OpenPGP
     message.  Note that this option may or may not remove a compression
     layer which is often found beneath the encryption layer.

'--tofu-policy {auto|good|unknown|bad|ask} KEYS'
     Set the TOFU policy for all the bindings associated with the
     specified KEYS.  For more information about the meaning of the
     policies, *note trust-model-tofu::.  The KEYS may be specified
     either by their fingerprint (preferred) or their keyid.