keyfork: tidy up some docs

keyfork/src/cli/derive.rs

@@ -17,10 +17,11 @@ type Result<T, E = Box<dyn std::error::Error>> = std::result::Result<T, E>;
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum DeriveSubcommands {
-    /// Derive an OpenPGP certificate.
+    /// Derive an OpenPGP Transferable Secret Key (private key). The key is encoded using OpenPGP
+    /// ASCII Armor, a format usable by most programs using OpenPGP.
     #[command(name = "openpgp")]
     OpenPGP {
-        /// Default User ID for the certificate.
+        /// Default User ID for the certificate, using the OpenPGP User ID format.
         user_id: String,
     },
 }

keyfork/src/cli/mod.rs

@@ -18,20 +18,21 @@ pub struct Keyfork {
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum KeyforkCommands {
-    /// Derive keys of various formats.
+    /// Derive keys of various formats. These commands require that the Keyfork server is running,
+    /// which can be started by running a `keyfork recover` command.
     Derive(derive::Derive),
 
     /// Mnemonic generation and persistence utilities.
     Mnemonic(mnemonic::Mnemonic),
 
-    /// Splitting and combining secrets using Shamir's Secret Sharing.
+    /// Splitting and combining secrets, using Shamir's Secret Sharing.
     Shard(shard::Shard),
 
-    /// Derive and deploy keys.
+    /// Derive and deploy keys to hardware.
     #[command(subcommand_negates_reqs(true))]
     Provision(provision::Provision),
 
-    /// Recover a seed using a recovery mechanism and begin the Keyfork daemon.
+    /// Recover a seed using the requested recovery mechanism and start the Keyfork server.
     Recover(recover::Recover),
 
     /// Utilities to automatically manage the setup of Keyfork.

keyfork/src/cli/recover.rs

@@ -18,7 +18,8 @@ pub enum RecoverSubcommands {
         key_discovery: Option<PathBuf>,
     },
 
-    /// Combine remotely decrypted shards.
+    /// Combine remotely decrypted shards. The shards should be sent using the command `keyfork
+    /// shard transport`.
     RemoteShard {},
 }