The buf command is a powerful tool for managing Protocol Buffers (Protobuf) projects. To use the command effectively, it
is important to understand the different ways in which inputs can be specified, including schemas, sources, images,
formats, arguments, and flags.
Schema
A schema refers to the .proto files that define the structure and organization of the data being serialized and
deserialized by the Protobuf messages. The schema is essentially a contract between the different components of the
system, specifying the fields, data types, and structure of the messages that can be exchanged between them.
Source
A source is a schema that is a collection of uncompiled Protobuf files in a project. It can be turned into an image
using buf build.
When specifying a source as an input, source formats can be used.
Image
An image is a schema that is a set of Protobuf files compiled into an Image binary. An Image represents everything inside a Protobuf project and can be used as the input to most commands. When specifying an image as an input, image formats can be used.
Format
The format of an input. This can specify the format of an argument, or the format of a flag. For
example buf curl --schema, buf breaking --against, or buf convert --to and --from all take format options.
When accepting schemas, most commands accept both source and image formats, although some, especially buf export
and [buf lint] do not take image formats as they operate directly on a source.
Formats are used to specify both schema formats and also standard payload data formats, for
example buf convert --from and --to take a format option of json and bin, but do not accept source formats as
they expect a paylaod.
Arguments
Many buf commands need a schema in either an image or source format, in most of these cases the first argument is used to specify this schema:
buf breaking <schema> [flags]
buf build <schema> [flags]
buf convert <schema> [flags]
buf export <schema> [flags]
buf format <schema> [flags]
buf generate <schema> [flags]
buf lint <schema> [flags]
The following commands do not take a schema as a first argument, but a url:
buf curl <url>
By default, the default argument of most buf commands is ., so any .proto files in the current directory will be used.
Flags
Flags are sometimes used because buf needs to have more than one input, or the argument of the command is not a schema
because one is optional, for example with buf curl.
The buf breaking command is has the flag --against that takes in a schema in either image or source formats:
buf breaking --against=schema.bin
buf breaking --against=/path/to/proj
The buf convert --from and --to are flags that accept payload data, but not a schema. They take a format option
of json and bin but do not accept source formats:
buf convert person.proto --from=person.bin --to=person.json --type=Person
The buf curl --schema flag is a flag that accepts a schema, similar to buf breaking --against:
buf curl --data '{}' --schema=buf.build/bufbuild/eliza https://demo.connect.build/buf.connect.demo.eliza.v1.ElizaService/Say