docs: tooling (#22049)
This commit is contained in:
Julien Robert
+94
-90
@@ -2,7 +2,9 @@
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# AutoCLI
|
||||
# Client/v2
|
||||
|
||||
## AutoCLI
|
||||
|
||||
:::note Synopsis
|
||||
This document details how to build CLI and REST interfaces for a module. Examples from various Cosmos SDK modules are included.
|
||||
@@ -14,9 +16,9 @@ This document details how to build CLI and REST interfaces for a module. Example
|
||||
|
||||
:::
|
||||
|
||||
The `autocli` (also known as `client/v2`) package is a [Go library](https://pkg.go.dev/cosmossdk.io/client/v2/autocli) for generating CLI (command line interface) interfaces for Cosmos SDK-based applications. It provides a simple way to add CLI commands to your application by generating them automatically based on your gRPC service definitions. Autocli generates CLI commands and flags directly from your protobuf messages, including options, input parameters, and output parameters. This means that you can easily add a CLI interface to your application without having to manually create and manage commands.
|
||||
The `autocli` (also known as `client/v2/autocli`) package is a [Go library](https://pkg.go.dev/cosmossdk.io/client/v2/autocli) for generating CLI (command line interface) interfaces for Cosmos SDK-based applications. It provides a simple way to add CLI commands to your application by generating them automatically based on your gRPC service definitions. Autocli generates CLI commands and flags directly from your protobuf messages, including options, input parameters, and output parameters. This means that you can easily add a CLI interface to your application without having to manually create and manage commands.
|
||||
|
||||
## Overview
|
||||
### Overview
|
||||
|
||||
`autocli` generates CLI commands and flags for each method defined in your gRPC service. By default, it generates commands for each gRPC services. The commands are named based on the name of the service method.
|
||||
|
||||
@@ -32,7 +34,7 @@ For instance, `autocli` would generate a command named `my-method` for the `MyMe
|
||||
|
||||
It is possible to customize the generation of transactions and queries by defining options for each service.
|
||||
|
||||
## Application Wiring
|
||||
### Application Wiring
|
||||
|
||||
Here are the steps to use AutoCLI:
|
||||
|
||||
@@ -73,7 +75,7 @@ if err := rootCmd.Execute(); err != nil {
|
||||
}
|
||||
```
|
||||
|
||||
### Keyring
|
||||
#### Keyring
|
||||
|
||||
`autocli` uses a keyring for key name resolving names and signing transactions.
|
||||
|
||||
@@ -100,7 +102,7 @@ keyring.NewAutoCLIKeyring(kb)
|
||||
|
||||
:::
|
||||
|
||||
## Signing
|
||||
### Signing
|
||||
|
||||
`autocli` supports signing transactions with the keyring.
|
||||
The [`cosmos.msg.v1.signer` protobuf annotation](https://docs.cosmos.network/main/build/building-modules/protobuf-annotations) defines the signer field of the message.
|
||||
@@ -110,7 +112,7 @@ This field is automatically filled when using the `--from` flag or defining the
|
||||
AutoCLI currently supports only one signer per transaction.
|
||||
:::
|
||||
|
||||
## Module wiring & Customization
|
||||
### Module wiring & Customization
|
||||
|
||||
The `AutoCLIOptions()` method on your module allows to specify custom commands, sub-commands or flags for each service, as it was a `cobra.Command` instance, within the `RpcCommandOptions` struct. Defining such options will customize the behavior of the `autocli` command generation, which by default generates a command for each method in your gRPC service.
|
||||
|
||||
@@ -131,7 +133,87 @@ AutoCLI can create a gov proposal of any tx by simply setting the `GovProposal`
|
||||
Users can however use the `--no-proposal` flag to disable the proposal creation (which is useful if the authority isn't the gov module on a chain).
|
||||
:::
|
||||
|
||||
### Conventions for the `Use` field in Cobra
|
||||
#### Specifying Subcommands
|
||||
|
||||
By default, `autocli` generates a command for each method in your gRPC service. However, you can specify subcommands to group related commands together. To specify subcommands, use the `autocliv1.ServiceCommandDescriptor` struct.
|
||||
|
||||
This example shows how to use the `autocliv1.ServiceCommandDescriptor` struct to group related commands together and specify subcommands in your gRPC service by defining an instance of `autocliv1.ModuleOptions` in your `autocli.go`.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-beta.0/x/gov/autocli.go#L94-L97
|
||||
```
|
||||
|
||||
#### Positional Arguments
|
||||
|
||||
By default `autocli` generates a flag for each field in your protobuf message. However, you can choose to use positional arguments instead of flags for certain fields.
|
||||
|
||||
To add positional arguments to a command, use the `autocliv1.PositionalArgDescriptor` struct, as seen in the example below. Specify the `ProtoField` parameter, which is the name of the protobuf field that should be used as the positional argument. In addition, if the parameter is a variable-length argument, you can specify the `Varargs` parameter as `true`. This can only be applied to the last positional parameter, and the `ProtoField` must be a repeated field.
|
||||
|
||||
Here's an example of how to define a positional argument for the `Account` method of the `auth` service:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-beta.0/x/auth/autocli.go#L25-L30
|
||||
```
|
||||
|
||||
Then the command can be used as follows, instead of having to specify the `--address` flag:
|
||||
|
||||
```bash
|
||||
<appd> query auth account cosmos1abcd...xyz
|
||||
```
|
||||
|
||||
#### Customising Flag Names
|
||||
|
||||
By default, `autocli` generates flag names based on the names of the fields in your protobuf message. However, you can customise the flag names by providing a `FlagOptions`. This parameter allows you to specify custom names for flags based on the names of the message fields.
|
||||
|
||||
For example, if you have a message with the fields `test` and `test1`, you can use the following naming options to customise the flags:
|
||||
|
||||
``` go
|
||||
autocliv1.RpcCommandOptions{
|
||||
FlagOptions: map[string]*autocliv1.FlagOptions{
|
||||
"test": { Name: "custom_name", },
|
||||
"test1": { Name: "other_name", },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
`FlagsOptions` is defined like sub commands in the `AutoCLIOptions()` method on your module.
|
||||
|
||||
#### Combining AutoCLI with Other Commands Within A Module
|
||||
|
||||
AutoCLI can be used alongside other commands within a module. For example, the `gov` module uses AutoCLI to generate commands for the `query` subcommand, but also defines custom commands for the `proposer` subcommands.
|
||||
|
||||
In order to enable this behavior, set in `AutoCLIOptions()` the `EnhanceCustomCommand` field to `true`, for the command type (queries and/or transactions) you want to enhance.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/fa4d87ef7e6d87aaccc94c337ffd2fe90fcb7a9d/x/gov/autocli.go#L98
|
||||
```
|
||||
|
||||
If not set to true, `AutoCLI` will not generate commands for the module if there are already commands registered for the module (when `GetTxCmd()` or `GetQueryCmd()` are defined).
|
||||
|
||||
#### Skip a command
|
||||
|
||||
AutoCLI automatically skips unsupported commands when [`cosmos_proto.method_added_in` protobuf annotation](https://docs.cosmos.network/main/build/building-modules/protobuf-annotations) is present.
|
||||
|
||||
Additionally, a command can be manually skipped using the `autocliv1.RpcCommandOptions`:
|
||||
|
||||
```go
|
||||
*autocliv1.RpcCommandOptions{
|
||||
RpcMethod: "Params", // The name of the gRPC service
|
||||
Skip: true,
|
||||
}
|
||||
```
|
||||
|
||||
#### Use AutoCLI for non module commands
|
||||
|
||||
It is possible to use `AutoCLI` for non module commands. The trick is still to implement the `appmodule.Module` interface and append it to the `appOptions.ModuleOptions` map.
|
||||
|
||||
For example, here is how the SDK does it for `cometbft` gRPC commands:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/main/client/grpc/cmtservice/autocli.go#L52-L71
|
||||
```
|
||||
|
||||
#### Conventions for the `Use` field in Cobra
|
||||
|
||||
According to the [Cobra documentation](https://pkg.go.dev/github.com/spf13/cobra#Command) the following conventions should be followed for the `Use` field in Cobra commands:
|
||||
|
||||
@@ -155,87 +237,7 @@ According to the [Cobra documentation](https://pkg.go.dev/github.com/spf13/cobra
|
||||
5. **Combination of options**:
|
||||
* Example: `command [-F file | -D dir]... [-f format] profile`
|
||||
|
||||
### Specifying Subcommands
|
||||
|
||||
By default, `autocli` generates a command for each method in your gRPC service. However, you can specify subcommands to group related commands together. To specify subcommands, use the `autocliv1.ServiceCommandDescriptor` struct.
|
||||
|
||||
This example shows how to use the `autocliv1.ServiceCommandDescriptor` struct to group related commands together and specify subcommands in your gRPC service by defining an instance of `autocliv1.ModuleOptions` in your `autocli.go`.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-beta.0/x/gov/autocli.go#L94-L97
|
||||
```
|
||||
|
||||
### Positional Arguments
|
||||
|
||||
By default `autocli` generates a flag for each field in your protobuf message. However, you can choose to use positional arguments instead of flags for certain fields.
|
||||
|
||||
To add positional arguments to a command, use the `autocliv1.PositionalArgDescriptor` struct, as seen in the example below. Specify the `ProtoField` parameter, which is the name of the protobuf field that should be used as the positional argument. In addition, if the parameter is a variable-length argument, you can specify the `Varargs` parameter as `true`. This can only be applied to the last positional parameter, and the `ProtoField` must be a repeated field.
|
||||
|
||||
Here's an example of how to define a positional argument for the `Account` method of the `auth` service:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-beta.0/x/auth/autocli.go#L25-L30
|
||||
```
|
||||
|
||||
Then the command can be used as follows, instead of having to specify the `--address` flag:
|
||||
|
||||
```bash
|
||||
<appd> query auth account cosmos1abcd...xyz
|
||||
```
|
||||
|
||||
### Customising Flag Names
|
||||
|
||||
By default, `autocli` generates flag names based on the names of the fields in your protobuf message. However, you can customise the flag names by providing a `FlagOptions`. This parameter allows you to specify custom names for flags based on the names of the message fields.
|
||||
|
||||
For example, if you have a message with the fields `test` and `test1`, you can use the following naming options to customise the flags:
|
||||
|
||||
``` go
|
||||
autocliv1.RpcCommandOptions{
|
||||
FlagOptions: map[string]*autocliv1.FlagOptions{
|
||||
"test": { Name: "custom_name", },
|
||||
"test1": { Name: "other_name", },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
`FlagsOptions` is defined like sub commands in the `AutoCLIOptions()` method on your module.
|
||||
|
||||
### Combining AutoCLI with Other Commands Within A Module
|
||||
|
||||
AutoCLI can be used alongside other commands within a module. For example, the `gov` module uses AutoCLI to generate commands for the `query` subcommand, but also defines custom commands for the `proposer` subcommands.
|
||||
|
||||
In order to enable this behavior, set in `AutoCLIOptions()` the `EnhanceCustomCommand` field to `true`, for the command type (queries and/or transactions) you want to enhance.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/fa4d87ef7e6d87aaccc94c337ffd2fe90fcb7a9d/x/gov/autocli.go#L98
|
||||
```
|
||||
|
||||
If not set to true, `AutoCLI` will not generate commands for the module if there are already commands registered for the module (when `GetTxCmd()` or `GetQueryCmd()` are defined).
|
||||
|
||||
### Skip a command
|
||||
|
||||
AutoCLI automatically skips unsupported commands when [`cosmos_proto.method_added_in` protobuf annotation](https://docs.cosmos.network/main/build/building-modules/protobuf-annotations) is present.
|
||||
|
||||
Additionally, a command can be manually skipped using the `autocliv1.RpcCommandOptions`:
|
||||
|
||||
```go
|
||||
*autocliv1.RpcCommandOptions{
|
||||
RpcMethod: "Params", // The name of the gRPC service
|
||||
Skip: true,
|
||||
}
|
||||
```
|
||||
|
||||
### Use AutoCLI for non module commands
|
||||
|
||||
It is possible to use `AutoCLI` for non module commands. The trick is still to implement the `appmodule.Module` interface and append it to the `appOptions.ModuleOptions` map.
|
||||
|
||||
For example, here is how the SDK does it for `cometbft` gRPC commands:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/main/client/grpc/cmtservice/autocli.go#L52-L71
|
||||
```
|
||||
|
||||
## Summary
|
||||
### Summary
|
||||
|
||||
`autocli` lets you generate CLI to your Cosmos SDK-based applications without any cobra boilerplate. It allows you to easily generate CLI commands and flags from your protobuf messages, and provides many options for customising the behavior of your CLI application.
|
||||
|
||||
@@ -245,7 +247,7 @@ For more information on `hubl`, including how to configure a new chain and query
|
||||
|
||||
# Off-Chain
|
||||
|
||||
Off-chain functionalities allow you to sign and verify files with two commands:
|
||||
Off-chain is a `client/v2` package providing functionalities for allowing to sign and verify files with two commands:
|
||||
|
||||
* `sign-file` for signing a file.
|
||||
* `verify-file` for verifying a previously signed file.
|
||||
@@ -275,6 +277,7 @@ The `encoding` flag lets you choose how the contents of the file should be encod
|
||||
"signer": "cosmos1x33fy6rusfprkntvjsfregss7rvsvyy4lkwrqu",
|
||||
"data": "Hello World!\n"
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
* `simd off-chain sign-file alice myFile.json --encoding base64`
|
||||
@@ -286,6 +289,7 @@ The `encoding` flag lets you choose how the contents of the file should be encod
|
||||
"signer": "cosmos1x33fy6rusfprkntvjsfregss7rvsvyy4lkwrqu",
|
||||
"data": "SGVsbG8gV29ybGQhCg=="
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
* `simd off-chain sign-file alice myFile.json --encoding hex`
|
||||
|
||||
Reference in New Issue
Block a user