Merge pull request #8678 from Agoric/gibson-2023-12-golang-cli-commands

style(golang): Align CLI command fields with upstream recommendations

golang/cosmos/daemon/cmd/genaccounts.go

@@ -29,12 +29,12 @@ const (
 // AddGenesisAccountCmd returns add-genesis-account cobra Command.
 func AddGenesisAccountCmd(defaultNodeHome string) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "add-genesis-account [address_or_key_name] [coin][,[coin]]",
+		Use:   "add-genesis-account <address_or_key_name> <coin>[,...]",
 		Short: "Add a genesis account to genesis.json",
-		Long: `Add a genesis account to genesis.json. The provided account must specify
-the account address or key name and a list of initial coins. If a key name is given,
-the address will be looked up in the local Keybase. The list of initial tokens must
-contain valid denominations. Accounts may optionally be supplied with vesting parameters.
+		Long: `Add a genesis account to genesis.json.
+If the address is specified by name, it will be looked up in the local Keybase.
+The comma-separated list of initial tokens must contain valid denominations.
+Accounts may optionally be supplied with vesting parameters.
 `,
 		Args: cobra.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {

golang/cosmos/daemon/cmd/testnet.go

@@ -37,7 +37,7 @@ import (
 
 var (
 	flagNodeDirPrefix     = "node-dir-prefix"
-	flagNumValidators     = "v"
+	flagNumValidators     = "validator-count"
 	flagOutputDir         = "output-dir"
 	flagNodeDaemonHome    = "node-daemon-home"
 	flagStartingIPAddress = "starting-ip-address"
@@ -48,13 +48,13 @@ func testnetCmd(mbm module.BasicManager, genBalIterator banktypes.GenesisBalance
 	cmd := &cobra.Command{
 		Use:   "testnet",
 		Short: fmt.Sprintf("Initialize files for a %s testnet", AppName),
-		Long: `testnet will create "v" number of directories and populate each with
+		Long: `testnet will create one directory per validator and populate each with
 necessary files (private validator, genesis, config, etc.).
 
 Note, strict routability for addresses is turned off in the config file.
 
 Example:
-	agd testnet --v 4 --output-dir ./output --starting-ip-address 192.168.10.2
+	agd testnet -n 4 --output-dir ./output --starting-ip-address 192.168.10.2
 	`,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			clientCtx, err := client.GetClientQueryContext(cmd)
@@ -74,16 +74,27 @@ Example:
 			numValidators, _ := cmd.Flags().GetInt(flagNumValidators)
 			algo, _ := cmd.Flags().GetString(flags.FlagKeyAlgorithm)
 
+			if cmd.Flags().Changed("v") {
+				if cmd.Flags().Changed(flagNumValidators) {
+					return fmt.Errorf("--%s and --v are mutually exclusive", flagNumValidators)
+				}
+				numValidators, _ = cmd.Flags().GetInt("v")
+			}
+
 			return InitTestnet(
 				clientCtx, cmd, config, mbm, genBalIterator, outputDir, chainID, minGasPrices,
 				nodeDirPrefix, nodeDaemonHome, startingIPAddress, keyringBackend, algo, numValidators,
 			)
 		},
 	}
 
-	cmd.Flags().Int(flagNumValidators, 4, "Number of validators to initialize the testnet with")
+	cmd.Flags().IntP(flagNumValidators, "n", 4, "Number of validators to initialize the testnet with")
+	cmd.Flags().Int("v", 4, fmt.Sprintf("Alias for --%s", flagNumValidators))
+	if vFlag := cmd.Flags().Lookup("v"); vFlag != nil {
+		vFlag.Deprecated = fmt.Sprintf("use --%s", flagNumValidators)
+	}
 	cmd.Flags().StringP(flagOutputDir, "o", "./mytestnet", "Directory to store initialization data for the testnet")
-	cmd.Flags().String(flagNodeDirPrefix, "node", "Prefix the directory name for each node with (node results in node0, node1, ...)")
+	cmd.Flags().String(flagNodeDirPrefix, "node", "Prefix for the name of per-validator subdirectories (to be number-suffixed like node0, node1, ...)")
 	cmd.Flags().String(flagNodeDaemonHome, AppName, "Home directory of the node's daemon configuration")
 	cmd.Flags().String(flagStartingIPAddress, "192.168.0.1", "Starting IP address (192.168.0.1 results in persistent peers list [email protected]:46656, [email protected]:46656, ...)")
 	cmd.Flags().String(flags.FlagChainID, "", "genesis file chain-id, if left blank will be randomly created")

golang/cosmos/x/swingset/client/cli/query.go

@@ -53,7 +53,7 @@ func GetCmdQueryParams(queryRoute string) *cobra.Command {
 
 func GetCmdGetEgress(queryRoute string) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "egress [account]",
+		Use:   "egress <account>",
 		Short: "get egress info for account",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -86,7 +86,7 @@ func GetCmdGetEgress(queryRoute string) *cobra.Command {
 // GetCmdMailbox queries information about a mailbox
 func GetCmdMailbox(queryRoute string) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "mailbox [peer]",
+		Use:   "mailbox <peer>",
 		Short: "get mailbox for peer",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {

golang/cosmos/x/swingset/client/cli/tx.go

@@ -44,11 +44,18 @@ func GetTxCmd(storeKey string) *cobra.Command {
 }
 
 // GetCmdDeliver is the CLI command for sending a DeliverInbound transaction
+// containing mailbox messages.
 func GetCmdDeliver() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "deliver [json string]",
-		Short: "deliver inbound messages",
-		Args:  cobra.ExactArgs(1),
+		Use:   "deliver {<messages JSON> | @- | @<file>}",
+		Short: "send mailbox messages",
+		Long: `send mailbox messages.
+The argument indicates how to read input JSON ("@-" for standard input,
+"@..." for a file path, and otherwise directly as in "deliver '[...]'").
+Input must represent an array in which the first element is an array of
+[messageNum: integer, messageBody: string] pairs and the second element
+is an "Ack" integer.`,
+		Args: cobra.ExactArgs(1),
 
 		RunE: func(cmd *cobra.Command, args []string) error {
 			cctx, err := client.GetClientTxContext(cmd)
@@ -91,7 +98,14 @@ func GetCmdDeliver() *cobra.Command {
 // InstallBundle message in a transaction.
 func GetCmdInstallBundle() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:  "install-bundle <JSON>/@<FILE>/-",
+		Use:   "install-bundle {<bundle JSON> | @- | @<file>}",
+		Short: "install a bundle",
+		Long: `install a bundle.
+The argument indicates how to read input JSON ("@-" for standard input,
+"@..." for a file path, and otherwise directly as in
+"install-bundle '{...}'").
+Input should be endoZipBase64 JSON, but this is not verified.
+https://github.com/endojs/endo/tree/master/packages/bundle-source`,
 		Args: cobra.ExactArgs(1),
 
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -147,7 +161,7 @@ func GetCmdInstallBundle() *cobra.Command {
 // GetCmdProvision is the CLI command for sending a Provision transaction
 func GetCmdProvisionOne() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "provision-one [nickname] [address] [power-flags]",
+		Use:   "provision-one <nickname> <address> [<power-flag>[,...]]",
 		Short: "provision a single address",
 		Args:  cobra.RangeArgs(2, 3),
 
@@ -185,7 +199,7 @@ func GetCmdProvisionOne() *cobra.Command {
 // GetCmdWalletAction is the CLI command for sending a WalletAction or WalletSpendAction transaction
 func GetCmdWalletAction() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "wallet-action [json string]",
+		Use:   "wallet-action <action JSON>",
 		Short: "perform a wallet action",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -220,9 +234,11 @@ func GetCmdWalletAction() *cobra.Command {
 	return cmd
 }
 
+// NewCmdSubmitCoreEvalProposal is the CLI command for submitting a "CoreEval"
+// governance proposal via `agd tx gov submit-proposal swingset-core-eval ...`.
 func NewCmdSubmitCoreEvalProposal() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "swingset-core-eval [[permit.json] [code.js]]...",
+		Use:   "swingset-core-eval <permit.json code.js>...",
 		Args:  cobra.MinimumNArgs(2),
 		Short: "Submit a proposal to evaluate code in the SwingSet core",
 		Long: `Submit a SwingSet evaluate core Compartment code proposal along with an initial deposit.

golang/cosmos/x/vstorage/client/cli/query.go

@@ -28,8 +28,8 @@ func GetQueryCmd(storeKey string) *cobra.Command {
 // GetCmdGetData queries information about storage
 func GetCmdGetData(queryRoute string) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "data [path]",
-		Short: "get vstorage data for path",
+		Use:   "data <path>",
+		Short: "get data for vstorage path",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			clientCtx, err := client.GetClientQueryContext(cmd)
@@ -60,8 +60,12 @@ func GetCmdGetChildren(queryRoute string) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "children [path]",
 		Aliases: []string{"keys"},
-		Short:   "get vstorage subkey names for path",
-		Args:    cobra.MaximumNArgs(1),
+		Short:   "get child path segments under vstorage path",
+		Long: `get child path segments under vstorage path.
+When absent, path defaults to the empty root path.
+Path segments are dot-separated, so a child "baz" under path "foo.bar" has path
+"foo.bar.baz".`,
+		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			clientCtx, err := client.GetClientQueryContext(cmd)
 			if err != nil {
@@ -92,7 +96,7 @@ func GetCmdGetChildren(queryRoute string) *cobra.Command {
 // GetCmdGetPath queries vstorage data or children, depending on the path
 func GetCmdGetPath(queryRoute string) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "path [path]",
+		Use:   "path <path>",
 		Short: "get vstorage data, or children if path ends with '.'",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {