APIs can be challenging to understand and consume from the command line, a utility most developers use daily. Tools like cURL facilitate command line API calls, but don't present the API surface. In this session we will look at an approach to generating intuitive command line utilities with Go & Cobra for gRPC APIs.

1. Proprietary + Confidential
Intuitive CLIs for gRPC
Noah Dietz
(@no_d_here)

2. @no_d_here
– Context
– State of the art
– Some more context...
– Generated Command Line Interfaces
– Goals & Non-Goals
– Demo
Agenda

3. Source: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis non erat sem
@no_d_here

4. Source: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis non erat sem
@no_d_here
source
source

5. Source: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis non erat sem
@no_d_here

6. @no_d_here
State of the Art
– Server reflection-based CLIs
● Closer to HTTP cURL
● Favors flexibility over API
consumption experience
– github.com/grpc/grpc/.../grpc_cli
– github.com/fullstorydev/grpcurl
#grpcurl example
# listing available Services
> grpcurl my.api.net list
MyService
# listing Service RPCs
> grpccurl my.api.net list MyService
MethodA
MethodB
# describing specific Service RPC
> grpccurl my.api.net describe MyService MethodA
…
# describing specific Service RPC
> grpccurl my.api.net describe MethodAInput
…
# invoking a Service RPC
> grpcurl -d '{"name": "Jane Doe"}'
my.api.net
MyService.MethodA
…

7. Source: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis non erat sem
@no_d_here

8. Source: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis non erat sem
@no_d_here
github.com/googleapis/kiosk

9. Source: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis non erat sem
@no_d_here
“Why wasn’t this CLI generated?”
- Tim Burks

10. Source: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis non erat sem
@no_d_here

11. Proprietary + Confidential
Generated Command Line Interfaces

12. @no_d_here
Goals
– Generate a more human-oriented
interface
– Generate a CLI tailored to a given
gRPC API
– Generate clean, idiomatic code for
client reference implementations
Non-Goals
– Provide a single, generic utility that can
invoke any gRPC API
– Replace gcloud SDK as the canonical
Google Cloud CLI

13. @no_d_here
Generated Command Line Interfaces (gcli)
– Go lang
– Cobra CLI framework
– Follows design patterns of Cobra framework
– Uses Google generated API clients (GAPIC)
– github.com/googleapis/gapic-generator-go

14. @no_d_here
– Intuitive command & argument structure
● Services → subcommands
RPCs → sub-subcommands
Message fields → flags
– Easy to learn the API
● “help” commands
● bash autocomplete generation
Tailored API Command Line Experience

15. @no_d_here
gcli as a Client Reference Implementation
– Clean, well-structured Go code
– Variable & command names that make sense
● message CreateKioskRequest → var CreateKioskInput *pb.CreateKioskRequest
● rpc CreateKiosk → var createKioskCmd → “k kiosk create-kiosk”
– All kinds of streaming, LRO, etc.

16. Proprietary + Confidential
Demo

17. @no_d_here

18. Proprietary + Confidential
Thank you!
Noah Dietz
(@no_d_here)