protoc-gen-go_cli

README

protoc-gen-go_cli

A protoc plugin that generates CLIs in Go for APIs described with protocol buffers.

Purpose

The goal of this plugin is to generate command line interface applications for gRPC APIs. A generated CLI should be intuitive and representative of the API surface.

Need to Know

The generated CLIs depend on both a generated Go gRPC library and a Go gapic generated by the neighboring protoc-gen-go_gapic plugin.

Furthermore, the generator respects the API design practices detailed in the Google Cloud API Design Guide.

Using the plugin

Examples used in the following documentation are drawn from the Kiosk API.

Install the plugin

go get github.com/googleapis/gapic-generator-go/cmd/protoc-gen-go_cli

Or install from source

mkdir -p $GOPATH/src/github.com/googleapis
cd $GOPATH/src/github.com/googleapis
git clone https://github.com/googleapis/gapic-generator-go.git
cd gapic-generator-go/cmd/protoc-gen-go_cli
go install

Invocation

protoc api.proto \
  --go_cli_out [OUTPUT DIR] \
  --go_cli_opt "root=[ROOT COMMAND]" \
  --go_cli_opt "gapic=[GAPIC IMPORT]"

Options explained

• root=[ROOT COMMAND]: root command used for the generated CLI. Example: Kiosk API -> root=kctl
• gapic=[GAPIC IMPORT]: Go import path for the gapic generated by protoc-gen-go_gapic (here). Example: gapic=github.com/googleapis/kiosk/kioskgapic. Optionally, provide the package name at the end separated with a semicolon, like so: gapic=github.com/googleapis/kiosk/apiv1;kioskgapic
• fmt=[true | false]: toggle for generating go/format'd output. Default true

Installing generated CLI

cd [OUTPUT DIR]
go get
go install

Printing usage

kctl --help
Root command of kctl

Usage:
  kctl [command]

Available Commands:
  completion  Emits bash a completion for kctl
  display     Sub-command for Service: Display
  help        Help about any command

Flags:
  -h, --help      help for kctl
  -j, --json      Print JSON output
  -v, --verbose   Print verbose output

Use "kctl [command] --help" for more information about a command.

About the generated CLI

CLI Framework

The generated CLI utilizes the cobra CLI framework along with the supporting viper and pflag libraries for configuration.

As such, features like bash completion script generation and usage/help documentation come built into the generated CLI.

The usage documentation for bash completion generation of the kctl CLI is as follows:

$ kctl completion --help
Enable bash completion like so:
Linux:
  source <(kctl completion)
Mac:
  brew install bash-completion
  kctl completion > $(brew --prefix)/etc/bash_completion.d/kctl

Configuration

The supported client configurations include:

• API address (--address): the host(:port) of the API
• Disable TLS (--insecure): toggle off TLS connections
• Bearer token (--token): bearer token to be used
• API Key (--api_key): API key to be used

Such configurations are available at the protobuf service level, which is the first subcommmand level of the generated CLI. Furthermore, each option can be configured using an environment variable with the naming scheme [ROOT COMMAND]_[SERVICE NAME]_[CONFIG VALUE]. For example, kiosk.Display address config -> KCTL_DISPLAY_ADDRESS.

Supported gRPC & API Features

Three of four RPC call types are supported, except bi-directional streaming. Supported:

• Unary
• Client Streaming
• Server Streaming

Review the gapic documentation for more information on supported transport-level features.

Furthermore, API-oriented features like long running operations and paged APIs are supported as well.

Input Payload

The protobuf Method's input Message fields are represented as flattened command line flags of a method subcommand. However, all input can be provided via the --from_file flag containing the absolute path to a file with a JSON representation of the payload.

Output

All response messages are emitted as plain text representations by default, but can be toggled to JSON using the global -j --json flag.

Furthermore, more vebrose output can be toggled on via the global -v --verbose flag.

Similar Projects

There are other projects that aim to supply command line interfaces for gRPC APIs. Related works include:

• grpcurl
• protoc-gen-cobra
• and many more at awesome-grpc