Skip to main content
The kratos proto command provides subcommands for working with Protocol Buffer files, including adding new proto templates, generating client code, and generating server implementations.

​
Usage

kratos proto <subcommand> [arguments] [flags]

​
Subcommands

add

Add a new proto API template

client

Generate client code from proto files

server

Generate server implementations from proto files

​
kratos proto add

Add a new proto API template file with boilerplate service definition.

​
Usage

kratos proto add <path/to/file.proto>

​
Arguments

  • path - The hierarchical path for the proto file (e.g., helloworld/v1/hello.proto)

​
Description

Creates a new proto file with a basic service template. The path must be hierarchical (contain at least one /).

​
Examples

# Add a new API proto file
kratos proto add api/helloworld/v1/greeter.proto
This generates a proto file with:
  • Package declaration based on the path
  • Go package option configured
  • Java package option configured
  • Basic service definition
The proto path must be hierarchical. Single-level paths like hello.proto are not allowed.

​
kratos proto client

Generate client code from proto files using protoc.

​
Usage

kratos proto client <proto-file-or-directory> [flags]

​
Arguments

  • proto-file-or-directory - Path to a single .proto file or a directory containing proto files

​
Flags

​
-p, --proto_path
string
default:"./third_party"
Path to search for proto dependencies. Can be overridden by setting the KRATOS_PROTO_PATH environment variable.
kratos proto client api/hello.proto -p ./proto

​
Description

Generates Go code from proto files using protoc with multiple plugins:
  • protoc-gen-go - Standard Go proto compiler
  • protoc-gen-go-grpc - gRPC service code
  • protoc-gen-go-http - Kratos HTTP transport code
  • protoc-gen-go-errors - Kratos error definitions
  • protoc-gen-openapi - OpenAPI specification
If required plugins are not found, the command automatically runs kratos upgrade to install them.

​
Generated Files

For a proto file api/helloworld/v1/greeter.proto, the following files are generated:
  • greeter.pb.go - Proto message definitions
  • greeter_grpc.pb.go - gRPC service definitions
  • greeter_http.pb.go - HTTP transport bindings
  • greeter_errors.pb.go - Error definitions
  • greeter.openapi.yaml - OpenAPI specification

​
Examples

​
Generate from Single File

kratos proto client api/helloworld/v1/greeter.proto

​
Generate from Directory

kratos proto client api
This walks through the directory and generates code for all .proto files (excluding third_party/).

​
Custom Proto Path

kratos proto client api --proto_path ./external/protos

​
Using Environment Variable

export KRATOS_PROTO_PATH=./proto
kratos proto client api
Ensure you have protoc installed on your system. The command requires:
  • protoc (Protocol Buffer compiler)
  • Kratos protoc plugins (installed automatically if missing)

​
kratos proto server

Generate server implementation stubs from proto service definitions.

​
Usage

kratos proto server <proto-file> [flags]

​
Arguments

  • proto-file - Path to the proto file containing service definitions

​
Flags

​
-t, --target-dir
string
default:"internal/service"
Directory where the generated service implementation files will be created.
kratos proto server api/greeter.proto -t internal/services

​
Description

Generates Go service implementation stubs from proto service definitions. For each service in the proto file, it creates a Go file with:
  • Service struct definition
  • Constructor function
  • Method stubs for all RPC methods
  • Proper imports and package declarations
The command supports all gRPC streaming types:
  • Unary RPC
  • Server streaming
  • Client streaming
  • Bidirectional streaming

​
Examples

​
Basic Usage

kratos proto server api/helloworld/v1/greeter.proto
Generates internal/service/greeter.go with implementation stubs.

​
Custom Target Directory

kratos proto server api/user/v1/user.proto --target-dir internal/services

​
Generated Code Structure

For a proto file with a Greeter service: 
package service

import (
    "context"
    pb "your-module/api/helloworld/v1"
)

type GreeterService struct {
    pb.UnimplementedGreeterServer
}

func NewGreeterService() *GreeterService {
    return &GreeterService{}
}

func (s *GreeterService) SayHello(ctx context.Context, req *pb.HelloRequest) (*pb.HelloReply, error) {
    return &pb.HelloReply{}, nil
}
The command will not overwrite existing service files. If a file already exists, it will be skipped with a warning message.

​
Complete Workflow Example

1

Add a new proto file

kratos proto add api/blog/v1/post.proto
2

Edit the proto file

Define your service and messages in the generated proto file.
3

Generate client code

kratos proto client api/blog/v1/post.proto
4

Generate server implementation

kratos proto server api/blog/v1/post.proto
5

Implement business logic

Fill in the generated service stubs in internal/service/post.go.

Build docs developers (and LLMs) love

Get started for freeTalk to us