20+ Commands

gRPC & Protocol Buffers (Protobuf) Commands Matrix

The definitive gRPC and Protocol Buffers cheat sheet: protoc code generation flags, grpcurl live API inspection, proto3 message and service syntax, repeated/oneof rules, and streaming RPCs with 1-click copy.

Protoc CLI & CodeGen (4 commands)

Protoc CLI & CodeGen

protoc --proto_path=proto --go_out=gen --go_opt=paths=source_relative proto/user.proto

Compiles .proto files into Go structs and serialization helper functions using protoc-gen-go.

PRO TIP Ensure protoc-gen-go is installed in your $GOBIN ($PATH).

Protoc CLI & CodeGen

protoc --proto_path=proto --go-grpc_out=gen --go-grpc_opt=paths=source_relative proto/user.proto

Generates Go gRPC client interfaces and server stubs from service RPC definitions.

PRO TIP In Protobuf v3, Go message code and gRPC service code are split into separate plugins.

Protoc CLI & CodeGen

protoc --proto_path=proto --ts_out=service=grpc-web:./src/gen proto/*.proto

Compiles Protocol Buffer definitions into TypeScript types and gRPC-Web clients for frontend browser apps.

PRO TIP Combine with Envoy proxy to bridge browser HTTP/1.1 requests to backend HTTP/2 gRPC services.

Protoc CLI & CodeGen

protoc --proto_path=proto --python_out=./gen --grpc_python_out=./gen proto/service.proto

Generates Python message bindings (_pb2.py) and gRPC client/server stubs (_pb2_grpc.py).

PRO TIP Install grpcio-tools via pip to compile proto definitions directly from Python.

gRPCurl Inspection (4 commands)

gRPCurl Inspection

grpcurl -plaintext localhost:50051 list

Queries a running gRPC server for all registered services using Server Reflection.

PRO TIP Requires gRPC server reflection enabled (reflection.Register(s) in Go).

gRPCurl Inspection

grpcurl -plaintext localhost:50051 describe user.v1.UserService

Describes all RPC methods, request types, and response types for a specified service.

PRO TIP Inspect schema contracts without needing the original local .proto source files.

gRPCurl Inspection

grpcurl -plaintext -d '{"id": "usr_102"}' localhost:50051 user.v1.UserService/GetUser

Executes an RPC call with a JSON request payload converted on the fly to protobuf binary.

PRO TIP JSON field names correspond directly to camelCase or original snake_case proto identifiers.

gRPCurl Inspection

grpcurl -H "Authorization: Bearer <token>" api.production.com:443 user.v1.UserService/ListUsers

Transmits custom metadata headers (like auth bearer tokens) over secure TLS gRPC connection.

PRO TIP Port 443 defaults to standard TLS; omit -plaintext for encrypted production endpoints.

Proto3 Syntax Patterns (4 commands)

Proto3 Syntax Patterns

syntax = "proto3";
package auth.v1;
option go_package = "example.com/gen/auth/v1;authv1";

Standard proto3 header specifying version, logical namespace package, and language target paths.

PRO TIP Always declare go_package to avoid compilation warnings in modern protoc compilers.

Proto3 Syntax Patterns

message UserProfile {
  string user_id = 1;
  string email = 2;
  repeated string roles = 3;
  map<string, string> metadata = 4;
}

Defines scalar fields, repeated arrays, and hash maps with 1-based unique field tag numbers.

PRO TIP Field numbers 1 to 15 take only 1 byte on the wire; assign them to the most frequently used fields.

Proto3 Syntax Patterns

oneof authentication {
  string password_hash = 10;
  string oauth_token = 11;
  string api_key = 12;
}

Defines mutually exclusive fields where setting one automatically clears all other fields in the oneof.

PRO TIP Saves memory and cleanly models variant state without nullable boilerplate.

Proto3 Syntax Patterns

service OrderService {
  rpc StreamOrders (OrderRequest) returns (stream OrderUpdate);
}

Server-streaming RPC definition where the client sends one request and receives a stream of messages.

PRO TIP Prefix both request and response with "stream" to establish bidirectional streaming pipelines.