Add examples to each cmd (cosmos#337)

notional-labs · Jan 4, 2021 · db25632 · db25632
1 parent f8acf82
commit db25632
Show file tree

Hide file tree

Showing 14 changed files with 285 additions and 3 deletions.
diff --git a/cmd/chains.go b/cmd/chains.go
@@ -9,6 +9,7 @@ import (
 	"net/url"
 	"os"
 	"path"
+	"strings"
 
 	"github.com/spf13/cobra"
 	"gopkg.in/yaml.v2"
@@ -47,6 +48,9 @@ func chainsAddrCmd() *cobra.Command {
 		Aliases: []string{"addr"},
 		Short:   "Returns a chain's configured key's address",
 		Args:    cobra.ExactArgs(1),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s chains address ibc-0
+$ %s ch addr ibc-0`, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			chain, err := config.Chains.Get(args[0])
 			if err != nil {
@@ -72,6 +76,11 @@ func chainsShowCmd() *cobra.Command {
 		Aliases: []string{"s"},
 		Short:   "Returns a chain's configuration data",
 		Args:    cobra.ExactArgs(1),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s chains show ibc-0 --json
+$ %s chains show ibc-0 --yaml
+$ %s ch s ibc-0 --json
+$ %s ch s ibc-0 --yaml`, appName, appName, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			c, err := config.Chains.Get(args[0])
 			if err != nil {
@@ -122,6 +131,9 @@ func chainsEditCmd() *cobra.Command {
 		Aliases: []string{"e"},
 		Short:   "Returns chain configuration data",
 		Args:    cobra.ExactArgs(3),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s chains edit ibc-0 trusting-period 32h
+$ %s ch e ibc-0 trusting-period 32h`, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			chain, err := config.Chains.Get(args[0])
 			if err != nil {
@@ -149,6 +161,9 @@ func chainsDeleteCmd() *cobra.Command {
 		Aliases: []string{"d"},
 		Short:   "Returns chain configuration data",
 		Args:    cobra.ExactArgs(1),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s chains delete ibc-0
+$ %s ch d ibc-0`, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return overWriteConfig(cmd, config.DeleteChain(args[0]))
 		},
@@ -161,6 +176,9 @@ func chainsListCmd() *cobra.Command {
 		Use:     "list",
 		Aliases: []string{"l"},
 		Short:   "Returns chain configuration data",
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s chains list
+$ %s ch l`, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			jsn, err := cmd.Flags().GetBool(flagJSON)
 			if err != nil {
@@ -231,6 +249,12 @@ func chainsAddCmd() *cobra.Command {
 		Use:     "add",
 		Aliases: []string{"a"},
 		Short:   "Add a new chain to the configuration file by passing a file (-f) or url (-u), or user input",
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s chains add
+$ %s ch a
+$ %s chains add --file chains/ibc0.json
+$ %s chains add --url http://relayer.com/ibc0.json
+`, appName, appName, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			var out *Config
 
@@ -272,6 +296,9 @@ func chainsAddDirCmd() *cobra.Command {
 		Args:    cobra.ExactArgs(1),
 		Short: `Add new chains to the configuration file from a directory 
 		full of chain configuration, useful for adding testnet configurations`,
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s chains add-dir testnet/chains/
+$ %s ch ad testnet/chains/`, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) (err error) {
 			var out *Config
 			if out, err = filesAdd(args[0]); err != nil {

diff --git a/cmd/config.go b/cmd/config.go
@@ -60,6 +60,9 @@ func configShowCmd() *cobra.Command {
 		Use:     "show",
 		Aliases: []string{"s", "list", "l"},
 		Short:   "Prints current configuration",
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s config show --home %s
+$ %s cfg list`, appName, defaultHome, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			home, err := cmd.Flags().GetString(flags.FlagHome)
 			if err != nil {
@@ -93,6 +96,9 @@ func configInitCmd() *cobra.Command {
 		Use:     "init",
 		Aliases: []string{"i"},
 		Short:   "Creates a default home directory at path defined by --home",
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s config init --home %s
+$ %s cfg i`, appName, defaultHome, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			home, err := cmd.Flags().GetString(flags.FlagHome)
 			if err != nil {
@@ -149,6 +155,9 @@ func configAddDirCmd() *cobra.Command {
 		Args:    cobra.ExactArgs(1),
 		Short: `Add new chains and paths to the configuration file from a
 		 directory full of chain and path configuration, useful for adding testnet configurations`,
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s config add-dir configs/
+$ %s cfg ad configs/`, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) (err error) {
 			var out *Config
 			if out, err = cfgFilesAdd(args[0]); err != nil {

diff --git a/cmd/dev.go b/cmd/dev.go
@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
+	"strings"
 
 	sdk "github.com/cosmos/cosmos-sdk/types"
 	"github.com/spf13/cobra"
@@ -32,6 +33,10 @@ func genesisCmd() *cobra.Command {
 		Aliases: []string{"gen"},
 		Short:   "fetch the genesis file for a configured chain",
 		Args:    cobra.ExactArgs(1),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s dev genesis ibc-0
+$ %s dev gen ibc-0
+$ %s development genesis ibc-2`, appName, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			c, err := config.Chains.Get(args[0])
 			if err != nil {
@@ -62,6 +67,10 @@ func listenCmd() *cobra.Command {
 		Aliases: []string{"l"},
 		Short:   "listen to all transaction and block events from a given chain and output them to stdout",
 		Args:    cobra.ExactArgs(1),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s dev listen ibc-0 --data --no-tx
+$ %s dev l ibc-1 --no-block
+$ %s development listen ibc-2 --no-tx`, appName, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			c, err := config.Chains.Get(args[0])
 			if err != nil {
@@ -100,6 +109,9 @@ func gaiaServiceCmd() *cobra.Command {
 		Use:   "gaia [user] [home]",
 		Short: "gaia returns a sample gaiad service file",
 		Args:  cobra.ExactArgs(2),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s dev gaia [user-name] [path-to-home]
+$ %s development gaia user /home/user`, appName, appName)),
 		Run: func(cmd *cobra.Command, args []string) {
 			fmt.Printf(`[Unit]
 Description=gaiad
@@ -125,6 +137,9 @@ func faucetService() *cobra.Command {
 		Use:   "faucet [user] [home] [chain-id] [key-name] [amount]",
 		Short: "faucet returns a sample faucet service file",
 		Args:  cobra.ExactArgs(5),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s dev faucet faucetuser /home/faucetuser ibc-0 testkey 1000000stake
+$ %s development faucet root /home/root ibc-1 testkey2 1000000stake`, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			chain, err := config.Chains.Get(args[2])
 			if err != nil {
@@ -163,7 +178,10 @@ func rlyService() *cobra.Command {
 		Use:     "relayer [path-name]",
 		Aliases: []string{"rly"},
 		Short:   "relayer returns a service file for the relayer to relay over an individual path",
-		Args:    cobra.ExactArgs(1),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s dev rly demo-path
+$ %s development relayer path-test`, appName, appName)),
+		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			user, home := os.Getenv("USER"), os.Getenv("HOME")
 			if user == "" || home == "" {

diff --git a/cmd/keys.go b/cmd/keys.go
@@ -53,6 +53,10 @@ func keysAddCmd() *cobra.Command {
 		Aliases: []string{"a"},
 		Short:   "adds a key to the keychain associated with a particular chain",
 		Args:    cobra.RangeArgs(1, 2),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s keys add ibc-0
+$ %s keys add ibc-1 key2
+$ %s k a ibc-2 testkey`, appName, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			chain, err := config.Chains.Get(args[0])
 			if err != nil {
@@ -107,6 +111,9 @@ func keysRestoreCmd() *cobra.Command {
 		Aliases: []string{"r"},
 		Short:   "restores a mnemonic to the keychain associated with a particular chain",
 		Args:    cobra.ExactArgs(3),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s keys restore ibc-0 testkey "[mnemonic-words]"
+$ %s k r ibc-1 faucet-key "[mnemonic-words]"`, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			keyName := args[1]
 			chain, err := config.Chains.Get(args[0])
@@ -139,6 +146,10 @@ func keysDeleteCmd() *cobra.Command {
 		Aliases: []string{"d"},
 		Short:   "deletes a key from the keychain associated with a particular chain",
 		Args:    cobra.RangeArgs(1, 2),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s keys delete ibc-0 -y
+$ %s keys delete ibc-1 key2 -y
+$ %s k d ibc-2 testkey`, appName, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			chain, err := config.Chains.Get(args[0])
 			if err != nil {
@@ -202,6 +213,9 @@ func keysListCmd() *cobra.Command {
 		Aliases: []string{"l"},
 		Short:   "lists keys from the keychain associated with a particular chain",
 		Args:    cobra.ExactArgs(1),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s keys list ibc-0
+$ %s k l ibc-1`, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			chain, err := config.Chains.Get(args[0])
 			if err != nil {
@@ -231,6 +245,10 @@ func keysShowCmd() *cobra.Command {
 		Aliases: []string{"s"},
 		Short:   "shows a key from the keychain associated with a particular chain",
 		Args:    cobra.RangeArgs(1, 2),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s keys show ibc-0
+$ %s keys show ibc-1 key2
+$ %s k s ibc-2 testkey`, appName, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			chain, err := config.Chains.Get(args[0])
 			if err != nil {
@@ -268,6 +286,9 @@ func keysExportCmd() *cobra.Command {
 		Aliases: []string{"e"},
 		Short:   "exports a privkey from the keychain associated with a particular chain",
 		Args:    cobra.ExactArgs(2),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s keys export ibc-0 testkey
+$ %s k e ibc-2 testkey`, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			keyName := args[1]
 			chain, err := config.Chains.Get(args[0])

diff --git a/cmd/light.go b/cmd/light.go
@@ -18,6 +18,7 @@ package cmd
 import (
 	"fmt"
 	"strconv"
+	"strings"
 
 	"github.com/cosmos/cosmos-sdk/client/flags"
 	tmclient "github.com/cosmos/cosmos-sdk/x/ibc/light-clients/07-tendermint/types"
@@ -50,6 +51,10 @@ func initLightCmd() *cobra.Command {
 	1. passing it a root of trust as a --hash/-x and --height
 	2. Use --force/-f to initialize from the configured node`,
 		Args: cobra.ExactArgs(1),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s light init ibc-0 --force
+$ %s light init ibc-1 --height 1406 --hash <hash>
+$ %s l i ibc-2 --force`, appName, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			chain, err := config.Chains.Get(args[0])
 			if err != nil {
@@ -104,6 +109,9 @@ func updateLightCmd() *cobra.Command {
 		Aliases: []string{"u"},
 		Short:   "Update the light client to latest header from configured node",
 		Args:    cobra.ExactArgs(1),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s light update ibc-0
+$ %s l u ibc-1`, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			chain, err := config.Chains.Get(args[0])
 			if err != nil {
@@ -136,6 +144,10 @@ func lightHeaderCmd() *cobra.Command {
 		Long: "Get a header from the light client database. 0 returns last" +
 			"trusted header and all others return the header at that height if stored",
 		Args: cobra.RangeArgs(1, 2),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s light header ibc-0
+$ %s light header ibc-1 1400
+$ %s l hdr ibc-2`, appName, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			chainID := args[0]
 			chain, err := config.Chains.Get(chainID)
@@ -194,6 +206,9 @@ func deleteLightCmd() *cobra.Command {
 		Aliases: []string{"d"},
 		Short:   "wipe the light client database, forcing re-initialzation on the next run",
 		Args:    cobra.ExactArgs(1),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s light delete ibc-0
+$ %s l d ibc-2`, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			chainID := args[0]
 			chain, err := config.Chains.Get(chainID)

diff --git a/cmd/paths.go b/cmd/paths.go
@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"io/ioutil"
 	"os"
+	"strings"
 
 	clienttypes "github.com/cosmos/cosmos-sdk/x/ibc/core/02-client/types"
 	conntypes "github.com/cosmos/cosmos-sdk/x/ibc/core/03-connection/types"
@@ -44,6 +45,9 @@ func pathsGenCmd() *cobra.Command {
 		Aliases: []string{"gen"},
 		Short:   "generate identifiers for a new path between src and dst, reusing any that exist",
 		Args:    cobra.ExactArgs(3),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s paths generate ibc-0 ibc-1 demo-path --force
+$ %s pth gen ibc-0 ibc-1 demo-path --unordered false --version ics20-2`, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) (err error) {
 			var (
 				src, dst, pth          = args[0], args[1], args[2]
@@ -313,6 +317,9 @@ func pathsDeleteCmd() *cobra.Command {
 		Aliases: []string{"d"},
 		Short:   "delete a path with a given index",
 		Args:    cobra.ExactArgs(1),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s paths delete demo-path
+$ %s pth d path-name`, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if _, err := config.Paths.Get(args[0]); err != nil {
 				return err
@@ -330,6 +337,10 @@ func pathsListCmd() *cobra.Command {
 		Use:     "list",
 		Aliases: []string{"l"},
 		Short:   "print out configured paths",
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s paths list --yaml
+$ %s paths list --json
+$ %s pth l`, appName, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			jsn, _ := cmd.Flags().GetBool(flagJSON)
 			yml, _ := cmd.Flags().GetBool(flagYAML)
@@ -386,6 +397,10 @@ func pathsShowCmd() *cobra.Command {
 		Aliases: []string{"s"},
 		Short:   "show a path given its name",
 		Args:    cobra.ExactArgs(1),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s paths show demo-path --yaml
+$ %s paths show demo-path --json
+$ %s pth s path-name`, appName, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			path, err := config.Paths.Get(args[0])
 			if err != nil {
@@ -431,6 +446,10 @@ func pathsAddCmd() *cobra.Command {
 		Aliases: []string{"a"},
 		Short:   "add a path to the list of paths",
 		Args:    cobra.ExactArgs(3),
+		Example: strings.TrimSpace(fmt.Sprintf(`
+$ %s paths add ibc-0 ibc-1 demo-path
+$ %s paths add ibc-0 ibc-1 demo-path --file paths/demo.json
+$ %s pth a ibc-0 ibc-1 demo-path`, appName, appName, appName)),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			src, dst := args[0], args[1]
 			_, err := config.Chains.Gets(src, dst)