Our mission at Buf is to replace the reigning REST/JSON paradigm of API development with schema-driven development. To that end, we aim to build a new ecosystem with Protocol Buffers as its foundation. We've chosen Protobuf because it's by far the most widely used and trusted interface description language (IDL) for APIs. But one thing that we felt has been missing is a single, unified tool that can serve as the basis for a dramatically upgraded experience of working with Protobuf. To put the ecosystem on a better path, we created the Buf CLI, or just
Now, after over two years of work, we're excited to announce that
buf has officially reached the v1.0 milestone. In this post, we want to introduce our CLI to those who are unfamiliar and lay out some of the implications of this 1.0 release.
To try out the
bufCLI for yourself, see our installation docs.
We built the
buf CLI to be a kind of "one-stop shop" for Protobuf development. We'll go over some of the core features here.
buf lint command enables you to lint
.proto files, which helps to ensure that your Protobuf sources comply with chosen best practices. It offers a built-in set of standardized lint rules rooted in ecosystem-wide best practices for structuring consistent, maintainable Protobuf schemas. You can configure which rules you want to apply to your Protobuf modules and also specify exceptions.
buf breaking command enables you to perform breaking change detection between any two Protobuf inputs. You can use this to ensure, for example, that the Protobuf sources in the
development branch of a Git repository are compatible with the
main branch. As with linting,
buf can apply specific breaking change rules.
buf generate command enables you to generate code stubs from Protobuf sources and configure your plugins and code output directories in a
buf.gen.yaml file. With this functionality, you can remove complex
protoc invocations from your workflows, which have traditionally been one of the rougher edges in Protobuf-based API development.
.proto files has long been a pain point in the Protobuf ecosystem. In the past, developers needed to manage Protobuf dependencies through vendoring, which is hard to scale and can be brittle.
buf solves this problem by enabling you to manage your Protobuf dependencies through configuration. In your
buf.yaml file you can list your Protobuf dependencies and pull recent references from the Buf Schema Registry or pin your dependencies to specific versions.
You can use the
buf CLI to interact with the Buf Schema Registry, which provides a centralized platform for managing Protobuf assets, like versioned Buf modules and Protobuf plugins, and features like remote code generation, generated Protobuf API documentation, and hosted Protobuf plugins. The BSR recently went beta and most BSR-related
buf actions are under the
buf beta command, but we aim to bring
buf's BSR functionality out of beta soon.
To us, the CLI isn't an ancillary tool or a sideshow; we treat it like a full-fledged product. Our policy is to never make breaking changes within a version of the CLI. Now that
buf has reached a stable 1.0, you can expect no breaking changes until v2.0—and we have no plans to ever release a v2.0. While we do intend to release new features in the
buf CLI, you can expect total stability for all of the functionality that you rely on.
If you're a current
buf user, we recommend upgrading to 1.0 now.
If you have questions about the Buf CLI or are having trouble using it, drop into our Slack channel and Buf's engineering team will get you squared away.