grpcli

README

grpcli

Create a very quick, very rudimentary CLI tool for your grpc service.

Quickstart

func main() {
    conn, _ := grpc.Dial(someAddr)
    client := pb.NewSomeServiceClient(conn)
    cmd := &cobra.Command{Usage: os.Args[0]}
    grpcli.MapClient(context.Background(), grpcobra.Wrap(cmd), client)
    _ = cmd.Execute()
}

Other CLI libraries

We provide grpcobra.Wrap to wrap up cobra commands in our expected interface type. It shouldn't be hard to create your own custom wrapper for almost any other CLI library.

How it works

Basically, grpcli uses reflection to walk through every method on the client, then maps the method call to a separate sub-command. It also looks at the request message type and generates a CLI flag for each field on the message.

What's Supported?

Simple message types will get mapped properly. Message types with nested messages, oneofs, and maybe even enums are not yet fully tested.

Unary RPCs and server-side streaming RPCs both work.

Examples

Check out [./testdata/client] and [./testdata/server] for a very simple example. You can run the server locally and use the client to call the RPCs.

Documentation

Index

• Constants
• func MapClient(ctx context.Context, cmd Command, client any) error
• type CLIFlag
  • func NewCLIFlag[T GRPCScalar](v T) *CLIFlag[T]
  • func (f *CLIFlag[T]) Set(in string) error
  • func (f *CLIFlag[T]) String() string
  • func (f *CLIFlag[T]) Type() string
  • func (f *CLIFlag[T]) Value() any
• type Command
• type Flag
• type FlagSet
• type GRPCScalar
• type Value

Constants

const (
	ErrNoClient = constErr("no client RPC methods found")
)

Functions

func MapClient

func MapClient(ctx context.Context, cmd Command, client any) error

MapClient maps a grpc service client's methods to cmd. If client is not a grpc client type, ErrNotClient will be wrapped and returned.

Types

type CLIFlag

type CLIFlag[T GRPCScalar] struct {
	// contains filtered or unexported fields
}

CLIFlag implements Value and Flag.

func NewCLIFlag

func NewCLIFlag[T GRPCScalar](v T) *CLIFlag[T]

NewCLIFlag constructs a new CLIFlag with v as its default value. This is made generic primarily to use a type union for GRPC scalar types, to make it clear which types are supported. If we had union or sum types, there'd be no real reason to use generics here.

func (*CLIFlag[T]) Set

func (f *CLIFlag[T]) Set(in string) error

func (*CLIFlag[T]) String

func (f *CLIFlag[T]) String() string

func (*CLIFlag[T]) Type

func (f *CLIFlag[T]) Type() string

func (*CLIFlag[T]) Value

func (f *CLIFlag[T]) Value() any

type Command

type Command interface {
	AddCommand(name, usage string) (Command, error)
	Flags() FlagSet

	// SetRun sets the run function for the Command.
	SetRun(func() error)
}

Command describes a command (or sub-command) that grpcli should map grpc service methods to.

type Flag

type Flag interface {
	Value() any
}

Flag describes the value of a flag, set at the CLI.

type FlagSet

type FlagSet interface {
	// Var adds a flag (referenced by name) to the FlagSet.
	Var(v Value, name, usage string) error
}

FlagSet describes a set of flags that grpcli needs in order to add flags to sub-commands.

type GRPCScalar

type GRPCScalar interface {
	float32 | float64 |
		int32 | int64 | uint32 | uint64 |
		bool | string | []byte
}

GRPCScalar is a type union containing all protobuf scalar types.

type Value

type Value interface {
	fmt.Stringer
	Set(string) error
	Type() string
}

Value is a value type that may be scanned from CLI flags.