Core Protocol Buffer Operations

/**
 * Build Protocol Buffer files into a Buf image
 * @param input - Proto files, directories, git repos, BSR modules, or archives
 */
buf build [flags] [input]

# Key flags:
--output, -o string              Output location for built image
--as-file-descriptor-set         Export as FileDescriptorSet instead of Buf image
--exclude-imports                Don't include imported files in the image
--exclude-source-info            Don't include source code info in the image
--type strings                   Include only specific message/service types
--path strings                   Include only files under these paths
--exclude-path strings           Exclude files under these paths

# Build to binary image
buf build -o image.bin

# Build to JSON format
buf build -o image.json

# Build only specific types
buf build --type mypackage.MyMessage -o filtered.bin

# Build excluding imports
buf build --exclude-imports -o image.bin

# Build from BSR module
buf build buf.build/googleapis/googleapis -o googleapis.bin

/**
 * Lint Protocol Buffer files according to configurable rules
 * @param input - Proto files, directories, git repos, BSR modules, or archives
 */
buf lint [flags] [input]

# Key flags:
--error-format string     Error format (text, json, config-ignore-yaml, msvs, junit, github-actions)
--path strings           Lint only files under these paths  
--exclude-path strings   Exclude files under these paths from linting

# Lint current directory
buf lint

# Lint with JSON output for CI/CD
buf lint --error-format json

# Lint specific paths only
buf lint --path proto/user --path proto/order

# Lint excluding test files
buf lint --exclude-path proto/test

# Lint remote repository
buf lint https://github.com/googleapis/googleapis.git

/**
 * Check for breaking changes between two sets of Protocol Buffer sources
 * @param input - Current proto files to check
 * @param against - Previous version to compare against (required)
 */
buf breaking [flags] [input] --against [against-input]

# Key flags:
--against string              Required. Source to check against for breaking changes
--against-config string      Configuration file for the against source
--against-registry           Use BSR for against source instead of local cache
--exclude-imports            Exclude imports from breaking change detection
--limit-to-input-files       Only check files in input, not dependencies
--path strings              Only check files under these paths
--exclude-path strings      Exclude files under these paths

# Check against main branch
buf breaking --against '.git#branch=main'

# Check against previous tag
buf breaking --against '.git#tag=v1.0.0'

# Check against BSR module
buf breaking --against buf.build/acme/petapis:v1.0.0

# Check only input files (not dependencies)
buf breaking --against '.git#branch=main' --limit-to-input-files

# Check specific paths only
buf breaking --against '.git#branch=main' --path proto/public

/**
 * Generate code from Protocol Buffer definitions using plugins
 * @param input - Proto files, directories, git repos, BSR modules, or archives
 */
buf generate [flags] [input]

# Key flags:
--template string         Generation template file (default: buf.gen.yaml)
--output, -o string      Base output directory
--clean                  Delete output directories before generation
--include-imports        Generate code for imported files
--include-wkt           Generate code for well-known types
--type strings          Generate code only for specific types
--exclude-type strings  Exclude specific types from generation
--path strings          Generate only for files under these paths
--exclude-path strings  Exclude files under these paths
--config string         Configuration file path
--error-format string   Error output format
--disable-symlinks      Disable symlink resolution

# Generate using default template
buf generate

# Generate with custom template
buf generate --template buf.gen.custom.yaml

# Generate to specific output directory
buf generate -o gen/

# Clean output before generation
buf generate --clean

# Generate including imports
buf generate --include-imports

# Generate specific types only
buf generate --type mypackage.UserService --type mypackage.User

# Generate from BSR module
buf generate buf.build/googleapis/googleapis

version: v1
plugins:
  - name: go
    out: gen/go
    opt: paths=source_relative
  - name: go-grpc
    out: gen/go
    opt: 
      - paths=source_relative
  - name: js
    out: gen/js
    opt: import_style=commonjs

/**
 * Format Protocol Buffer files following industry standards
 * @param input - Proto files, directories, git repos, BSR modules, or archives
 */
buf format [flags] [input]

# Key flags:
--write, -w             Write formatted files back to disk (in-place editing)
--diff, -d              Show diff instead of formatted content
--exit-code             Exit with non-zero code if there are formatting differences
--output, -o string     Output directory (default: stdout)
--path strings          Format only files under these paths
--exclude-path strings  Exclude files under these paths

# Format and print to stdout
buf format

# Format files in place
buf format --write

# Show formatting diff
buf format --diff

# Check formatting in CI (exits with code 1 if changes needed)
buf format --diff --exit-code

# Format specific paths only
buf format --write --path proto/user

# Format to output directory
buf format -o formatted/ proto/

# Local file paths and directories
/path/to/proto/files
./proto
../shared-protos

# Git repositories with references
https://github.com/owner/repo.git
https://github.com/owner/repo.git#branch=main
https://github.com/owner/repo.git#tag=v1.0.0
https://github.com/owner/repo.git#ref=abc1234

# BSR modules with optional references
buf.build/owner/module
buf.build/owner/module:latest
buf.build/owner/module:v1.0.0

# Archive files
https://example.com/protos.tar.gz
./protos.zip

# Stdin
-

# Binary formats
image.bin                # Buf binary image format
descriptor.binpb         # FileDescriptorSet binary format

# Text formats  
image.json              # JSON representation
descriptor.txtpb        # Text protobuf format
image.yaml             # YAML representation (some operations)

# Error format options
--error-format text              # Human-readable (default)
--error-format json              # Machine-readable JSON
--error-format config-ignore-yaml # YAML format for config ignore
--error-format msvs              # Microsoft Visual Studio format
--error-format junit             # JUnit XML for CI/CD
--error-format github-actions    # GitHub Actions annotations

# Standard exit codes
0    # Success
1    # General error (invalid flags, file not found, etc.)
100  # Lint violations or breaking changes detected