protoc-gen-cobra

Cobra command line tool generator for Go gRPC.

What's this?

A plugin for the protobuf compiler protoc, that generates Go code using cobra. It is capable of generating client code for command line tools consistent with your protobuf description.

This:

service Bank {
	rpc Deposit(DepositRequest) returns (DepositReply)
}

message DepositRequest {
	string account = 1;
	double amount = 2;
}

message DepositReply {
	string account = 1;
	double balance = 2;
}

produces a client that can do:

echo '{"account":"foobar","amount":10}' | command bank deposit

It generates one cobra.Command per gRPC service (e.g. bank). The service's rpc methods are sub-commands, and share the same command line semantics. They take a request file for input, or stdin, and prints the response to the terminal, in the specified format. The client currently supports basic connectivity settings such as tls on/off, tls client authentication and so on.

$ ./example bank deposit -h
Deposit client

You can use environment variables with the same name of the command flags.
All caps and s/-/_, e.g. SERVER_ADDR.

Usage:
  example bank deposit [flags]

Examples:

Save a sample request to a file (or refer to your protobuf descriptor to create one):
	deposit -p > req.json

Submit request using file:
	deposit -f req.json

Authenticate using the Authorization header (requires transport security):
	export AUTH_TOKEN=your_access_token
	export SERVER_ADDR=api.example.com:443
	echo '{json}' | deposit --tls

Flags:
      --auth-token string          authorization token
      --auth-token-type string     authorization token type (default "Bearer")
      --jwt-key string             jwt key
      --jwt-key-file string        jwt key file
  -p, --print-sample-request       print sample request file and exit
  -f, --request-file string        client request file (must be json, yaml, or xml); use "-" for stdin + json
  -o, --response-format string     response format (json, prettyjson, yaml, or xml) (default "json")
  -s, --server-addr string         server address in form of host:port (default "localhost:8080")
      --timeout duration           client connection timeout (default 10s)
      --tls                        enable tls
      --tls-ca-cert-file string    ca certificate file
      --tls-cert-file string       client certificate file
      --tls-insecure-skip-verify   INSECURE: skip tls checks
      --tls-key-file string        client key file
      --tls-server-name string     tls server name override

This is an experiment. Was bored of writing the same boilerplate code to interact with gRPC servers, wanted something like kubectl. At some point I might want to generate server code too, similar to what go-swagger does. Perhaps look at using go-openapi too. Tests are lacking.

Streams

gRPC client and server streams are supported, you can do pipes from the command line. On server streams, each response is printed out using the specified response format. Client streams input must be formatted as json, one document per line, from a file or stdin.

Example client stream:

$ cat req.json
{"key":"hello","value":"world"}
{"key":"foo","value":"bar"}

$ ./example cache multiset -f req.json

Example client and server streams:

$ echo -ne '{"key":"hello"}\n{"key":"foo"}\n' | ./example cache multiget
{"value":"world"}
{"value":"bar"}

Idle server streams hang until the server closes the stream, or a timeout occurs.