doc+cmd: generate description from commands

Author: guggero

cmd/chantools/chanbackup.go

@@ -21,7 +21,12 @@ func newChanBackupCommand() *cobra.Command {
 	cc.cmd = &cobra.Command{
 		Use:   "chanbackup",
 		Short: "Create a channel.backup file from a channel database",
-		RunE:  cc.Execute,
+		Long: `This command creates a new channel.backup from a 
+channel.db file.`,
+		Example: `chantools chanbackup --rootkey xprvxxxxxxx \
+	--channeldb ~/.lnd/data/graph/mainnet/channel.db \
+	--multi_file new_channel_backup.backup`,
+		RunE: cc.Execute,
 	}
 	cc.cmd.Flags().StringVar(
 		&cc.ChannelDB, "channeldb", "", "lnd channel.db file to "+

cmd/chantools/compactdb.go

@@ -26,6 +26,11 @@ func newCompactDBCommand() *cobra.Command {
 		Use: "compactdb",
 		Short: "Create a copy of a channel.db file in safe/read-only " +
 			"mode",
+		Long: `This command opens a database in read-only mode and tries
+to create a copy of it to a destination file, compacting it in the process.`,
+		Example: `chantools compactdb \
+	--sourcedb ~/.lnd/data/graph/mainnet/channel.db \
+	--destdb ./results/compacted.db`,
 		RunE: cc.Execute,
 	}
 	cc.cmd.Flags().Int64Var(

cmd/chantools/derivekey.go

@@ -10,19 +10,23 @@ import (
 )
 
 type deriveKeyCommand struct {
-	BIP39   bool
-	Path    string
-	Neuter  bool
+	BIP39  bool
+	Path   string
+	Neuter bool
 
 	rootKey *rootKey
-	cmd *cobra.Command
+	cmd     *cobra.Command
 }
 
 func newDeriveKeyCommand() *cobra.Command {
 	cc := &deriveKeyCommand{}
 	cc.cmd = &cobra.Command{
-		Use: "derivekey",
+		Use:   "derivekey",
 		Short: "Derive a key with a specific derivation path",
+		Long: `This command derives a single key with the given BIP32
+derivation path from the root key and prints it to the console.`,
+		Example: `chantools derivekey --rootkey xprvxxxxxxxxxx \
+	--path "m/1017'/0'/5'/0/0'" --neuter`,
 		RunE: cc.Execute,
 	}
 	cc.cmd.Flags().BoolVar(
@@ -40,7 +44,7 @@ func newDeriveKeyCommand() *cobra.Command {
 	)
 
 	cc.rootKey = newRootKey(cc.cmd, "decrypting the backup")
-	
+
 	return cc.cmd
 }
 

cmd/chantools/dumpbackup.go

@@ -15,23 +15,27 @@ type dumpBackupCommand struct {
 	MultiFile string
 
 	rootKey *rootKey
-	cmd *cobra.Command
+	cmd     *cobra.Command
 }
 
 func newDumpBackupCommand() *cobra.Command {
 	cc := &dumpBackupCommand{}
 	cc.cmd = &cobra.Command{
 		Use:   "dumpbackup",
 		Short: "Dump the content of a channel.backup file",
-		RunE:  cc.Execute,
+		Long: `This command dumps all information that is inside a 
+channel.backup file in a human readable format.`,
+		Example: `chantools dumpbackup --rootkey xprvxxxxxxxxxx \
+	--multi_file ~/.lnd/data/chain/bitcoin/mainnet/channel.backup`,
+		RunE: cc.Execute,
 	}
 	cc.cmd.Flags().StringVar(
 		&cc.MultiFile, "multi_file", "", "lnd channel.backup file to "+
 			"dump",
 	)
 
 	cc.rootKey = newRootKey(cc.cmd, "decrypting the backup")
-	
+
 	return cc.cmd
 }
 

cmd/chantools/dumpchannels.go

@@ -23,6 +23,10 @@ func newDumpChannelsCommand() *cobra.Command {
 		Use: "dumpchannels",
 		Short: "Dump all channel information from an lnd channel " +
 			"database",
+		Long: `This command dumps all open and pending channels from the
+given lnd channel.db gile in a human readable format.`,
+		Example: `chantools dumpchannels \
+	--channeldb ~/.lnd/data/graph/mainnet/channel.db`,
 		RunE: cc.Execute,
 	}
 	cc.cmd.Flags().StringVar(

cmd/chantools/filterbackup.go

@@ -26,6 +26,11 @@ func newFilterBackupCommand() *cobra.Command {
 		Use: "filterbackup",
 		Short: "Filter an lnd channel.backup file and remove certain " +
 			"channels",
+		Long: `Filter an lnd channel.backup file by removing certain 
+channels (identified by their funding transaction outpoints).`,
+		Example: `chantools filterbackup --rootkey xprvxxxxxxxxxx \
+	--multi_file ~/.lnd/data/chain/bitcoin/mainnet/channel.backup \
+	--discard 2abcdef2b2bffaaa...db0abadd:1,4abcdef2b2bffaaa...db8abadd:0`,
 		RunE: cc.Execute,
 	}
 	cc.cmd.Flags().StringVar(

cmd/chantools/fixoldbackup.go

@@ -25,6 +25,13 @@ func newFixOldBackupCommand() *cobra.Command {
 		Short: "Fixes an old channel.backup file that is affected by " +
 			"the lnd issue #3881 (unable to derive shachain root " +
 			"key)",
+		Long: `Fixes an old channel.backup file that is affected by the
+lnd issue [#3881](https://github.com/lightningnetwork/lnd/issues/3881)
+(<code>[lncli] unable to restore chan backups: rpc error: code = Unknown desc =
+unable to unpack chan backup: unable to derive shachain root key: unable to
+derive private key</code>).`,
+		Example: `chantools fixoldbackup --rootkey xprvxxxxxxxxxx \
+	--multi_file ~/.lnd/data/chain/bitcoin/mainnet/channel.backup`,
 		RunE: cc.Execute,
 	}
 	cc.cmd.Flags().StringVar(

cmd/chantools/forceclose.go

@@ -35,6 +35,22 @@ func newForceCloseCommand() *cobra.Command {
 		Use: "forceclose",
 		Short: "Force-close the last state that is in the channel.db " +
 			"provided",
+		Long: `If you are certain that a node is offline for good (AFTER
+you've tried SCB!) and a channel is still open, you can use this method to
+force-close your latest state that you have in your channel.db.
+
+**!!! WARNING !!! DANGER !!! WARNING !!!**
+
+If you do this and the state that you publish is *not* the latest state, then
+the remote node *could* punish you by taking the whole channel amount *if* they
+come online before you can sweep the funds from the time locked (144 - 2000
+blocks) transaction *or* they have a watch tower looking out for them.
+
+**This should absolutely be the last resort and you have been warned!**`,
+		Example: `chantools forceclose --rootkey xprvxxxxxxxxxx \
+	--fromsummary results/summary-xxxx-yyyy.json
+	--channeldb ~/.lnd/data/graph/mainnet/channel.db \
+	--publish`,
 		RunE: cc.Execute,
 	}
 	cc.cmd.Flags().StringVar(

cmd/chantools/genimportscript.go

@@ -33,6 +33,22 @@ func newGenImportScriptCommand() *cobra.Command {
 		Short: "Generate a script containing the on-chain " +
 			"keys of an lnd wallet that can be imported into " +
 			"other software like bitcoind",
+		Long: `Generates a script that contains all on-chain private (or
+public) keys derived from an lnd 24 word aezeed wallet. That script can then be
+imported into other software like bitcoind.
+
+The following script formats are currently supported:
+* bitcoin-cli: Creates a list of bitcoin-cli importprivkey commands that can
+  be used in combination with a bitcoind full node to recover the funds locked
+  in those private keys.
+* bitcoin-cli-watchonly: Does the same as bitcoin-cli but with the
+  bitcoin-cli importpubkey command. That means, only the public keys are 
+  imported into bitcoind to watch the UTXOs of those keys. The funds cannot be
+  spent that way as they are watch-only.
+* bitcoin-importwallet: Creates a text output that is compatible with
+  bitcoind's importwallet command.`,
+		Example: `chantools genimportscript --format bitcoin-cli \
+	--recoverywindow 5000`,
 		RunE: cc.Execute,
 	}
 	cc.cmd.Flags().StringVar(

cmd/chantools/removechannel.go

@@ -24,6 +24,8 @@ func newRemoveChannelCommand() *cobra.Command {
 	cc.cmd = &cobra.Command{
 		Use:   "removechannel",
 		Short: "Remove a single channel from the given channel DB",
+		Example: `chantools --channeldb ~/.lnd/data/graph/mainnet/channel.db \
+	--channel 3149764effbe82718b280de425277e5e7b245a4573aa4a0203ac12cee1c37816:0`,
 		RunE:  cc.Execute,
 	}
 	cc.cmd.Flags().StringVar(