Skip to content

Buf CLI#

The Buf CLI is the command-line tool for working with Protocol Buffers, and Buf’s day-to-day replacement for protoc. Point it at a directory of .proto files and it covers most of what you actually do with Protobuf: compiling and formatting the files, detecting breaking changes against a previous version, generating code in any language, calling gRPC or Connect APIs with the schemas it already knows about, and publishing the result to the Buf Schema Registry.

Configuration lives in a YAML file at the root of your project. There’s no need to assemble long protoc invocations or maintain -I include paths by hand: Buf walks your directory and figures out which files belong together.

Why the Buf CLI#

protoc is Google’s Protobuf compiler, and it gets the job done, but scaling it up past a handful of files tends to involve a growing pile of shell scripts around --proto_path, plugins installed by hand, and the faint hope that nothing has quietly drifted since the last build. 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.
  • 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 unlocks extras like remote plugins, hosted dependency resolution for private modules, and generated SDKs, but it’s not a prerequisite for the core CLI.

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.