Thanks to visit codestin.com
Credit goes to buf.build

Skip to content

Buf CLI#

The Buf CLI is the modern toolchain for Protocol Buffers. It replaces day-to-day protoc use with a fast compiler, module-aware workspaces, formatting, linting, breaking-change detection, code generation, dependency management, API calls, and a client for the Buf Schema Registry.

If you’re still driving Protobuf with shell scripts around protoc -I ..., Buf is the upgrade path: the same schema language, the same generated-code plugin model, fewer moving parts, and a direct route from local .proto files to governed, versioned APIs.

Configuration lives in YAML files at the root of your project. Instead of assembling long compiler invocations or maintaining include paths by hand, you declare modules once in buf.yaml; Buf discovers files, rejects ambiguous imports, and makes build, lint, breaking-change detection, generation, dependency resolution, and publishing agree on the same input.

Why the Buf CLI#

protoc is Google’s Protobuf compiler, and it gets the job done. Scaling it across real repositories is where the workflow frays: include paths move into scripts, plugin versions drift across machines, compatibility checks become optional, and API consumers get handed schemas plus generation instructions instead of a stable package. The Buf CLI addresses those rough edges directly:

  • Automatic file discovery. Buf finds your .proto files on its own, following the module layout you declare in buf.yaml. No --proto_path gymnastics.
  • Built-in lint and breaking-change detection. Over 40 lint rules and 50 breaking-change rules, grouped into opinionated default sets, run straight from the command line or in CI. There’s no separate plugin to install.
  • Parallel compilation. The internal compiler uses every available core and still produces byte-for-byte deterministic output, which works out to roughly twice the throughput of protoc on a non-trivial workspace.
  • Universal inputs. Commands like lint, breaking, and generate treat local directories, Git repositories, tarballs, zip files, and prebuilt Buf images as interchangeable inputs. You can lint a remote Git branch the same way you lint your working tree.
  • Native BSR dependency management. Declare dependencies on modules hosted in the Buf Schema Registry in your buf.yaml, and buf dep update resolves them into a buf.lock file. It’s the same workflow you already know from go.mod, package.json, and Cargo.toml, applied to Protobuf.
  • A path from local schemas to consumers. buf push publishes named modules to the BSR, where consumers can depend on them by name, browse generated docs, and install generated SDKs with their normal package manager.
  • Editor integration via the language server protocol. buf lsp serve runs as an LSP server, so lint diagnostics, formatting, and navigation work in VS Code, JetBrains, Vim, Emacs, or any other LSP-aware editor.

Everything above works without a BSR account. Signing in to the Buf Schema Registry turns the local toolchain into a distribution workflow: private dependency resolution, remote plugins, generated SDKs, hosted documentation, Studio access, and server-side checks for organizations that need registry-level governance.

What the CLI can do#

Commands grouped by task. See the CLI reference for complete flag listings.

Compile#

Check quality and compatibility#

  • buf lint: Check .proto files against style and structure rules.
  • buf breaking: Compare a schema against a previous version and flag incompatible changes.
  • buf format: Reformat .proto files to a canonical style.

Generate code#

Call APIs#

  • buf curl: Call a gRPC, gRPC-Web, or Connect endpoint, using your schema to encode the request and decode the response.
  • buf convert: Convert a Protobuf message between the binary wire format and JSON.

Manage dependencies#

  • buf dep: Resolve, trim, and visualize the BSR modules listed under deps in your buf.yaml, via the update, prune, and graph subcommands.

Manage configuration files#

  • buf config: Create and migrate buf.yaml files, and list the lint rules, breaking-change rules, and modules a workspace sees.

Work with the Buf Schema Registry#

  • buf push: Publish the current workspace as a module commit on the BSR.
  • buf export: Download the .proto files for a BSR module into a local directory.
  • buf registry: Log in and out, and manage BSR organizations, modules, plugins, policies, and generated SDKs from the command line.
  • buf plugin: Publish and manage custom check plugins that extend buf lint and buf breaking.

Run as an editor language server#

Configuration#

The CLI is configured through YAML files at the root of your workspace:

  • buf.yaml: Declares the workspace. That includes which directories contain modules, each module’s name, dependencies on BSR modules, and which lint and breaking-change rules to enforce. Every project has one.
  • buf.gen.yaml: Configures buf generate. It lists the plugins to run, where to write their output, and which options to pass.

Get started#

  1. Install the Buf CLI via Homebrew, npm, a binary download, or Docker.
  2. Run the CLI quickstart. In about ten minutes it walks you from an empty workspace to a working Connect server, with detours through code generation, lint fixes, and a breaking change you have to catch.
  3. For individual topics, the sub-guides go deeper: linting, breaking-change detection, code generation, editor integration, and modules and workspaces. Once you’re ready to share schemas across teams, pick up the BSR quickstart.

The CLI is stable: the project commits to no breaking changes within the v1.x series, and has no plans to ship a v2.0. See the CLI breaking-change policy for the full text.