This article follows the official documentation. We haven’t tested this tool for a hands-on review.
When a coding agent edits an API defined with Protocol Buffers, it needs a way to check whether the schema follows project rules and remains compatible with existing clients. Buf CLI provides those checks alongside commands for formatting, building, and generating code. A Protocol Buffers schema, often called a Protobuf schema, is a set of .proto files that describes messages and services.
An agent can run Buf from the repository’s shell to lint changed schemas and compare them with a baseline, the version used for comparison, such as the main branch. Buf reads and validates schema files during these checks; it does not write generated code. The commands below use the repository’s existing Buf configuration and assume a local Git branch named main.
Check schema changes locally
Buf reads project settings from buf.yaml, including the module definition and lint or compatibility rules. A module is the set of Protobuf files Buf treats as one unit. Repositories that generate code can also use buf.gen.yaml to specify code-generation plugins and settings. Buf’s migration documentation explains these configuration files and how Buf works with other Protobuf tools.
Install Buf by following the official installation instructions. On macOS or Linux with Homebrew, install it and check that the executable is available:
brew install bufbuild/buf/buf
buf --version
From the repository root, an agent can run the two local checks:
buf lint
buf breaking --against '.git#branch=main'
buf lint checks the schema against the repository’s configured lint rules. Buf offers rule categories such as MINIMAL, BASIC, and STANDARD; the project’s configuration determines which rules apply. The Buf lint rule reference describes the categories and individual rules.
buf breaking compares the working schema with the selected baseline and reports changes that violate the configured compatibility rules. The breaking-change command reference explains the command and its flags. In this example, '.git#branch=main' tells Buf to use the local Git branch named main as the comparison source. If the repository uses another base branch, replace main with that branch name.
Both commands run from the local checkout. Comparing against a local Git branch does not require a Buf Schema Registry login. A project that imports private modules from the Buf Schema Registry, which hosts Protobuf modules, or compares against a registry reference requires network access and authentication. Follow Buf’s CI and authentication setup for private registry access, and provide credentials through the environment or a secret store rather than placing them in an agent prompt.
Read the results and choose the next step
By default, Buf prints human-readable text. For machine-readable output, set the --error-format flag. The breaking-change reference lists JSON and JUnit as values, and also formats for GitHub Actions and GitLab Code Quality. For example:
buf breaking --against '.git#branch=main' --error-format=json
An agent can inspect reported violations in JSON, but a developer must decide whether a proposed schema change meets the compatibility requirements of the service’s clients. buf lint and buf breaking validate schemas; buf generate is a separate command that runs configured code-generation plugins and writes generated files.
A breaking-change check also depends on the baseline. Buf’s CI guidance warns that concurrent changes can make the results misleading if the feature branch does not include the latest changes from main. If the check reports a conflict or unexpected incompatibility, update the branch from the intended base and rerun the check before treating the result as final.
“Inspect the Protobuf changes, run buf lint and buf breaking --against '.git#branch=main', and summarize any reported violations. Do not edit generated files or change the Buf configuration.”
Coding agents can use Buf CLI to run the same schema checks developers run locally. Run the checks separately from code generation, and confirm that the comparison branch matches the baseline the project intends to enforce. The Awesome CLI directory lists other command-line tools for agent-accessible development work.