base on The best way of working with Protocol Buffers.  # Buf [](https://github.com/bufbuild/buf/blob/main/LICENSE) [](https://github.com/bufbuild/buf/releases) [](https://github.com/bufbuild/buf/actions?workflow=ci) [](https://hub.docker.com/r/bufbuild/buf) [](https://github.com/bufbuild/homebrew-buf) [][badges_slack] <a name="features"></a> The [`buf`][buf] CLI is the best tool for working with [Protocol Buffers][protobuf]. It provides: - A [linter][lint_usage] that enforces good API design choices and structure. - A [breaking change detector][breaking_tutorial] that enforces compatibility at the source code or wire level. - A [generator][generate_usage] that invokes your plugins based on configurable [templates][templates]. - A [formatter][format_usage] that formats your Protobuf files in accordance with industry standards. - Integration with the [Buf Schema Registry][bsr], including full dependency management. ## Installation ### Homebrew You can install `buf` using [Homebrew][brew] (macOS or Linux): ```sh brew install bufbuild/buf/buf ``` This installs: - The `buf`, [`protoc-gen-buf-breaking`][breaking], and [`protoc-gen-buf-lint`][lint] binaries - Shell completion scripts for [Bash], [Fish], [Powershell], and [zsh] ### Other methods For other installation methods, see our [official documentation][install], which covers: - Installing `buf` via [npm] - Installing `buf` on [Windows] - Using `buf` as a [Docker image][docker] - Installing as a [binary], from a [tarball], and from [source] through [GitHub Releases][releases] - [Verifying] releases using a [minisign] public key ## Usage Buf's help interface provides summaries for commands and flags: ```sh buf --help ``` For more comprehensive usage information, consult Buf's [documentation][docs], especially these guides: * [`buf breaking`][breaking_tutorial] * [`buf build`][build_usage] * [`buf generate`][generate_usage] * [`buf lint`][lint_usage] * [`buf format`][format_usage] * [`buf registry`][bsr_usage] (for using the [BSR]) ## CLI breaking change policy We will never make breaking changes within a given major version of the CLI. After `buf` reached v1.0, you can expect no breaking changes until v2.0. But as we have no plans to ever release a v2.0, we will likely never break the `buf` CLI. > This breaking change policy does _not_ apply to commands behind the `buf beta` gate, and you should expect breaking changes to commands like `buf beta registry`. The policy does go into effect, however, when those commands or flags are elevated out of beta. ## Our goals for Protobuf [Buf]'s goal is to replace the current paradigm of API development, centered around REST/JSON, with a **schema-driven** paradigm. Defining APIs using an [IDL] provides numerous benefits over REST/JSON, and [Protobuf] is by far the most stable and widely adopted IDL in the industry. We've chosen to build on this widely trusted foundation rather than creating a new IDL from scratch. But despite its technical merits, actually _using_ Protobuf has long been more challenging than it needs to be. The Buf CLI and the [BSR](#the-buf-schema-registry) are the cornerstones of our effort to change that for good and to make Protobuf reliable and easy to use for service owners and clients alike—in other words, to create a **modern Protobuf ecosystem**. While we intend to incrementally improve on the `buf` CLI and the [BSR](#the-buf-schema-registry), we're confident that the basic groundwork for such an ecosystem is _already_ in place. ## The Buf Schema Registry The [Buf Schema Registry][bsr] (BSR) is a SaaS platform for managing your Protobuf APIs. It provides a centralized registry and a single source of truth for all of your Protobuf assets, including not just your `.proto` files but also [remote plugins][bsr_plugins]. Although the BSR provides an intuitive browser UI, `buf` enables you to perform most BSR-related tasks from the command line, such as [pushing] Protobuf sources to the registry and managing [users] and [repositories]. > The BSR is not required to use `buf`. We've made the core [features] of the `buf` CLI available to _all_ Protobuf users. ## More advanced CLI features While `buf`'s [core features][features] should cover most use cases, we've included some more advanced features to cover edge cases: * **Automatic file discovery**. Buf walks your file tree and builds your `.proto` files in accordance with your supplied [build configuration][build_config], which means that you no longer need to manually specify `--proto_paths`. You can still, however, specify `.proto` files manually through CLI flags in cases where file discovery needs to be disabled. * **Fine-grained rule configuration** for [linting][lint_rules] and [breaking changes][breaking_rules]. While we do have recommended defaults, you can always select the exact set of rules that your use case requires, with [40 lint rules][lint_rules] and [53 breaking change rules][breaking_rules] available. * **Configurable error formats** for CLI output. `buf` outputs information in `file:line:column:message` form by default for each lint error and breaking change it encounters, but you can also select JSON, MSVS, JUnit, and Github Actions output. * **Editor integration** driven by `buf`'s granular error output. We currently provide linting integrations for both [Vim and Visual Studio Code][ide] and [JetBrains IDEs][jetbrains] like IntelliJ and GoLand, but we plan to support other editors such as Emacs in the future. * **Universal Input targeting**. Buf enables you to perform actions like linting and breaking change detection not just against local `.proto` files but also against a broad range of other [Inputs], such as tarballs and ZIP files, remote Git repositories, and pre-built [image][images] files. * **Speed**. Buf's internal Protobuf [compiler] compiles your Protobuf sources using all available cores without compromising deterministic output, which is considerably faster than `protoc`. This allows for near-instantaneous feedback, which is of special importance for features like [editor integration][ide]. ## Next steps Once you've installed `buf`, we recommend completing the [CLI tutorial][cli-tutorial], which provides a broad but hands-on overview of the core functionality of the CLI. The tour takes about 10 minutes to complete. After completing the tour, check out the remainder of the [docs] for your specific areas of interest. ## Community For help and discussion around Protobuf, best practices, and more, join us on [Slack][badges_slack]. For updates on the Buf CLI, [follow this repo on GitHub][repo]. For feature requests, bugs, or technical questions, email us at [[email protected]][email_dev]. For general inquiries or inclusion in our upcoming feature betas, email us at [[email protected]][email_info]. [badges_slack]: https://buf.build/links/slack [bash]: https://www.gnu.org/software/bash [binary]: https://buf.build/docs/installation#binary [breaking]: https://buf.build/docs/breaking/overview [breaking_rules]: https://buf.build/docs/breaking/rules [breaking_tutorial]: https://buf.build/docs/breaking/tutorial [brew]: https://brew.sh [bsr]: https://buf.build/docs/bsr/introduction [bsr_plugins]: https://buf.build/plugins [bsr_usage]: https://buf.build/docs/bsr/module/dependency-management [buf]: https://buf.build [build_config]: https://buf.build/docs/build/usage/#key-concepts [build_usage]: https://buf.build/docs/build/usage [cli-tutorial]: https://buf.build/docs/tutorials/getting-started-with-buf-cli [compiler]: https://buf.build/docs/reference/internal-compiler [docker]: https://buf.build/docs/installation#use-the-docker-image [docs]: https://buf.build/docs [email_dev]: mailto:[email protected] [email_info]: mailto:[email protected] [features]: #features [fish]: https://fishshell.com [format_usage]: https://buf.build/docs/format/style [generate_usage]: https://buf.build/docs/generate/tutorial [ide]: https://buf.build/docs/editor-integration [idl]: https://en.wikipedia.org/wiki/Interface_description_language [images]: https://buf.build/docs/reference/images [inputs]: https://buf.build/docs/reference/inputs [install]: https://buf.build/docs/installation [jetbrains]: https://buf.build/docs/editor-integration#jetbrains-ides [lint]: https://buf.build/docs/lint/overview [lint_rules]: https://buf.build/docs/lint/rules [lint_usage]: https://buf.build/docs/lint/tutorial [npm]: https://buf.build/docs/installation#npm [minisign]: https://github.com/jedisct1/minisign [powershell]: https://docs.microsoft.com/en-us/powershell [protobuf]: https://protobuf.dev [pushing]: https://buf.build/docs/bsr/module/dependency-management#push-a-module [releases]: https://buf.build/docs/installation#github-releases [repo]: https://github.com/bufbuild/buf/ [repositories]: https://buf.build/docs/bsr/introduction#module [source]: https://buf.build/docs/installation#from-source [tarball]: https://buf.build/docs/installation#tarball [templates]: https://buf.build/docs/configuration/v1/buf-gen-yaml [users]: https://buf.build/docs/admin/manage-members [verifying]: https://buf.build/docs/installation#var-selection-github-verifying-a-release [windows]: https://buf.build/docs/installation#windows-support [zsh]: https://zsh.org ", Assign "at most 3 tags" to the expected json: {"id":"3117","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"