CheatPress

buf Protobuf toolkit

Version 1.75.0 · source

buf, Postcard, light preview Light · Postcard 102 × 152 mm · PDF buf, Postcard, dark preview Dark · Postcard 102 × 152 mm · PDF buf, Postcard, ink saver preview Ink saver · Postcard 102 × 152 mm · PDF
buf, A5, light preview Light · A5 148 × 210 mm · PDF buf, A5, dark preview Dark · A5 148 × 210 mm · PDF buf, A5, ink saver preview Ink saver · A5 148 × 210 mm · PDF
buf, A4, light preview Light · A4 210 × 297 mm · PDF buf, A4, dark preview Dark · A4 210 × 297 mm · PDF buf, A4, ink saver preview Ink saver · A4 210 × 297 mm · PDF
buf, A4 landscape, light preview Light · A4 landscape 297 × 210 mm · PDF buf, A4 landscape, dark preview Dark · A4 landscape 297 × 210 mm · PDF buf, A4 landscape, ink saver preview Ink saver · A4 landscape 297 × 210 mm · PDF
buf, A3, light preview Light · A3 297 × 420 mm · PDF buf, A3, dark preview Dark · A3 297 × 420 mm · PDF buf, A3, ink saver preview Ink saver · A3 297 × 420 mm · PDF
buf, A3 landscape, light preview Light · A3 landscape 420 × 297 mm · PDF buf, A3 landscape, dark preview Dark · A3 landscape 420 × 297 mm · PDF buf, A3 landscape, ink saver preview Ink saver · A3 landscape 420 × 297 mm · PDF
buf, Letter, light preview Light · Letter 8.5 × 11 in · PDF buf, Letter, dark preview Dark · Letter 8.5 × 11 in · PDF buf, Letter, ink saver preview Ink saver · Letter 8.5 × 11 in · PDF
buf, Tabloid, light preview Light · Tabloid 11 × 17 in · PDF buf, Tabloid, dark preview Dark · Tabloid 11 × 17 in · PDF buf, Tabloid, ink saver preview Ink saver · Tabloid 11 × 17 in · PDF

Start here

buf config init
Create buf.yaml
buf build
Compile and check protos
buf lint
Check style rules
buf format -w
Format files in place
buf breaking --against <input>
Detect breaking changes
buf generate
Generate code
buf dep update
Pin dependencies
buf curl <url>
Call an RPC

Concepts

  1. proto files buf.yaml module
  2. Checked source style ok
  3. Compatible vs. last release
  4. Generated code buf.gen.yaml

Setup and config

buf --version
Print the installed version
buf config init
Create a buf.yaml here
buf config init buf.build/<owner>/<repo>
Create buf.yaml with a module name
buf config ls-lint-rules
List available lint rules
buf config ls-breaking-rules
List available breaking rules
buf config ls-modules
List modules in the workspace
buf config migrate
Upgrade config files to v2
buf <command> --help
Help for any command
buf --help-tree
Print the whole command tree
buf <command> --debug
Debug logging
buf <command> --timeout 5m
Limit how long a command runs

Build

buf build
Compile all protos in the module
Fails with the same errors protoc would report; a quick sanity check in CI.
buf build -o image.binpb
Write a binary image
buf build -o image.json
Write the image as JSON
buf build --as-file-descriptor-set -o fds.binpb
Write a plain FileDescriptorSet
buf build --path <dir/file.proto>
Build only part of the module
buf build --exclude-path <path>
Skip files or directories
buf build --type <pkg.Message>
Keep only one type and its deps
buf build --exclude-imports
Leave imports out of the image
buf build --exclude-source-info
Drop comments and source locations
buf build --error-format json
Machine-readable build errors

Lint

buf lint
Lint the current module
buf lint <input>
Lint a dir, git ref or image
buf lint --path <file.proto>
Lint selected files only
buf lint --exclude-path <path>
Skip files or directories
buf lint --error-format github-actions
Annotations for GitHub Actions
buf lint --error-format json
Machine-readable violations
buf lint --error-format config-ignore-yaml
Print ignore_only YAML for violations
Paste the output into buf.yaml to baseline existing violations.
buf lint --config '<json-or-yaml>'
Override config inline or by path
Lint categories
Category Meaning
STANDARD Default, recommended rules
BASIC Smaller subset of STANDARD
MINIMAL Package layout only
COMMENTS Require comments (opt in)
UNARY_RPC Forbid streaming RPCs (opt in)
// buf:lint:ignore <RULE_ID>
Silence one rule above a line
Place it directly before the element; disallow_comment_ignores: true turns it off.

Format

buf format
Print formatted files to stdout
buf format -w
Rewrite files in place
buf format -d
Show a diff instead
buf format -d --exit-code
Fail if anything is unformatted (CI)
buf format <file.proto> -o <out.proto>
Write result to another file
buf format --stdin-filepath <file.proto>
Format one file read from stdin
buf format --path <dir>
Format only part of the module

Breaking changes

buf breaking --against '.git#branch=main'
Compare with main in git
buf breaking --against <dir>
Compare with another directory
buf breaking --against image.binpb
Compare with a saved image
buf breaking --against-registry
Compare with the latest BSR commit
buf breaking --against <input> --path <dir>
Check only part of the module
buf breaking --against <input> --exclude-imports
Ignore changes in imports
buf breaking --against <input> --limit-to-input-files
Check only the input's files
buf breaking --against <input> --error-format github-actions
Annotations for CI
Breaking categories
Category Catches changes that break
FILE Generated source per file (default)
PACKAGE Generated source per package
WIRE_JSON Wire and JSON encoding
WIRE Wire encoding only
buf build -o baseline.binpb
Save a baseline image of a release

Generate

buf generate
Run plugins from buf.gen.yaml
buf generate --template <file.yaml>
Use another template file
buf generate --template '<json>'
Inline template as JSON
buf generate --path <dir>
Generate for part of the module
buf generate --exclude-path <path>
Skip files or directories
buf generate --include-imports
Also generate code for imports
Well-known types are not included.
buf generate --clean
Delete plugin output dirs first
buf generate -o <dir>
Prefix every plugin out dir
buf generate <input>
Generate from a git repo or module
buf generate --type <pkg.Message>
Only code for the listed types

Dependencies and modules

buf dep update
Resolve deps and write buf.lock
buf dep graph
Print the dependency graph
buf dep prune
Remove unused entries from buf.lock
buf export <input> -o <dir>
Copy protos and deps into a dir
buf stats
Count files, messages, services
buf push
Push the module to the BSR
buf lsp serve
Start the language server for editors

Convert and call

buf convert <input> --type <pkg.Msg> --from <file>.json --to <file>.binpb
Convert a message between formats
buf convert <input> --type <pkg.Msg> --from -#format=json
Read the payload from stdin
buf convert <input> --type <pkg.Msg> --from <file>.json --validate
Check against protovalidate rules
buf curl --list-services <url>
List services via reflection
buf curl --list-methods <url>
List methods via reflection
buf curl -d '<json>' <url>/<pkg.Svc>/<Method>
Call an RPC with a JSON body
buf curl -d @<file>.json <url>/<pkg.Svc>/<Method>
Read the body from a file
buf curl --schema <dir> <url>/<pkg.Svc>/<Method>
Use local protos, no reflection
buf curl --protocol grpc <url>/<pkg.Svc>/<Method>
Speak gRPC (default is Connect)
buf curl -H "Authorization: Bearer <token>" <url>/<pkg.Svc>/<Method>
Send a header
buf curl --http2-prior-knowledge <url>/<pkg.Svc>/<Method>
Plaintext HTTP/2 (h2c)
buf curl -v <url>/<pkg.Svc>/<Method>
Show request and response details
buf curl --emit-defaults <url>/<pkg.Svc>/<Method>
Include default values in JSON
buf curl -k <url>/<pkg.Svc>/<Method>
Skip TLS verification
buf curl --cacert <ca.pem> --cert <c.pem> --key <k.pem> <url>/<pkg.Svc>/<Method>
Mutual TLS

Config files

buf.yaml
version: v2modules:  - path: protodeps:  - buf.build/googleapis/googleapislint:  use:    - STANDARD  except:    - PACKAGE_VERSION_SUFFIXbreaking:  use:    - FILE
buf.gen.yaml
version: v2clean: trueplugins:  - remote: buf.build/protocolbuffers/go    out: gen/go    opt: paths=source_relative  - local: protoc-gen-go-grpc    out: gen/goinputs:  - directory: proto
Managed mode
managed:  enabled: true  override:    - file_option: go_package_prefix      value: example.com/gen/go

Recipes

CI checks
buf format -d --exit-codebuf lintbuf buildbuf breaking --against '.git#branch=main'
Fresh code generation
buf dep updatebuf generate --cleangit diff --exit-code gen/
Debug a payload
buf convert proto --type acme.v1.User \  --from user.json --to user.binpbbuf curl --schema proto -d @user.json \  http://localhost:8080/acme.v1.UserService/Get
Explore a server
buf curl --list-services http://localhost:8080buf curl --list-methods http://localhost:8080