github.com/cosmos/cosmos-sdk@v0.50.10/docs/architecture/adr-058-auto-generated-cli.md (about)

     1  # ADR 058: Auto-Generated CLI
     2  
     3  ## Changelog
     4  
     5  * 2022-05-04: Initial Draft
     6  
     7  ## Status
     8  
     9  ACCEPTED Partially Implemented
    10  
    11  ## Abstract
    12  
    13  In order to make it easier for developers to write Cosmos SDK modules, we provide infrastructure which automatically
    14  generates CLI commands based on protobuf definitions.
    15  
    16  ## Context
    17  
    18  Current Cosmos SDK modules generally implement a CLI command for every transaction and every query supported by the
    19  module. These are handwritten for each command and essentially amount to providing some CLI flags or positional
    20  arguments for specific fields in protobuf messages.
    21  
    22  In order to make sure CLI commands are correctly implemented as well as to make sure that the application works
    23  in end-to-end scenarios, we do integration tests using CLI commands. While these tests are valuable on some-level,
    24  they can be hard to write and maintain, and run slowly. [Some teams have contemplated](https://github.com/regen-network/regen-ledger/issues/1041)
    25  moving away from CLI-style integration tests (which are really end-to-end tests) towards narrower integration tests
    26  which exercise `MsgClient` and `QueryClient` directly. This might involve replacing the current end-to-end CLI
    27  tests with unit tests as there still needs to be some way to test these CLI commands for full quality assurance.
    28  
    29  ## Decision
    30  
    31  To make module development simpler, we provide infrastructure - in the new [`client/v2`](https://github.com/cosmos/cosmos-sdk/tree/main/client/v2)
    32  go module - for automatically generating CLI commands based on protobuf definitions to either replace or complement
    33  handwritten CLI commands. This will mean that when developing a module, it will be possible to skip both writing and
    34  testing CLI commands as that can all be taken care of by the framework.
    35  
    36  The basic design for automatically generating CLI commands is to:
    37  
    38  * create one CLI command for each `rpc` method in a protobuf `Query` or `Msg` service
    39  * create a CLI flag for each field in the `rpc` request type
    40  * for `query` commands call gRPC and print the response as protobuf JSON or YAML (via the `-o`/`--output` flag)
    41  * for `tx` commands, create a transaction and apply common transaction flags
    42  
    43  In order to make the auto-generated CLI as easy to use (or easier) than handwritten CLI, we need to do custom handling
    44  of specific protobuf field types so that the input format is easy for humans:
    45  
    46  * `Coin`, `Coins`, `DecCoin`, and `DecCoins` should be input using the existing format (i.e. `1000uatom`)
    47  * it should be possible to specify an address using either the bech32 address string or a named key in the keyring
    48  * `Timestamp` and `Duration` should accept strings like `2001-01-01T00:00:00Z` and `1h3m` respectively
    49  * pagination should be handled with flags like `--page-limit`, `--page-offset`, etc.
    50  * it should be possible to customize any other protobuf type either via its message name or a `cosmos_proto.scalar` annotation
    51  
    52  At a basic level it should be possible to generate a command for a single `rpc` method as well as all the commands for
    53  a whole protobuf `service` definition. It should be possible to mix and match auto-generated and handwritten commands.
    54  
    55  ## Consequences
    56  
    57  ### Backwards Compatibility
    58  
    59  Existing modules can mix and match auto-generated and handwritten CLI commands so it is up to them as to whether they
    60  make breaking changes by replacing handwritten commands with slightly different auto-generated ones.
    61  
    62  For now the SDK will maintain the existing set of CLI commands for backwards compatibility but new commands will use
    63  this functionality.
    64  
    65  ### Positive
    66  
    67  * module developers will not need to write CLI commands
    68  * module developers will not need to test CLI commands
    69  * [lens](https://github.com/strangelove-ventures/lens) may benefit from this
    70  
    71  ### Negative
    72  
    73  ### Neutral
    74  
    75  ## Further Discussions
    76  
    77  We would like to be able to customize:
    78  
    79  * short and long usage strings for commands
    80  * aliases for flags (ex. `-a` for `--amount`)
    81  * which fields are positional parameters rather than flags
    82  
    83  It is an [open discussion](https://github.com/cosmos/cosmos-sdk/pull/11725#issuecomment-1108676129)
    84  as to whether these customizations options should line in:
    85  
    86  * the .proto files themselves,
    87  * separate config files (ex. YAML), or
    88  * directly in code
    89  
    90  Providing the options in .proto files would allow a dynamic client to automatically generate
    91  CLI commands on the fly. However, that may pollute the .proto files themselves with information that is only relevant
    92  for a small subset of users.
    93  
    94  ## References
    95  
    96  * https://github.com/regen-network/regen-ledger/issues/1041
    97  * https://github.com/cosmos/cosmos-sdk/tree/main/client/v2
    98  * https://github.com/cosmos/cosmos-sdk/pull/11725#issuecomment-1108676129