or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration-management.mdcore-operations.mddependency-management.mdexperimental-features.mdindex.mdpolicy-management.mdregistry-operations.mdutility-operations.md
tile.json

tessl/golang-bufbuild--buf

The buf CLI is the best tool for working with Protocol Buffers, providing linting, breaking change detection, code generation, formatting, and integration with the Buf Schema Registry for modern Protobuf development workflows

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
golangpkg:golang/github.com/bufbuild/buf@1.57.x

To install, run

npx @tessl/cli install tessl/golang-bufbuild--buf@1.57.0

index.mddocs/

Buf CLI

Buf is a comprehensive CLI toolkit for Protocol Buffer development that modernizes the Protobuf ecosystem through advanced tooling and workflow automation. It provides essential features including API linting, breaking change detection, code generation, automatic formatting, and seamless integration with the Buf Schema Registry for centralized schema management.

Package Information

  • Package Name: buf
  • Package Type: golang
  • Language: Go
  • Installation: Download from GitHub releases or install via package managers:
    • macOS: brew install bufbuild/buf/buf
    • Linux: curl -sSL https://github.com/bufbuild/buf/releases/latest/download/buf-Linux-x86_64.tar.gz | tar -xvzf - -C /usr/local --strip-components 1
    • Windows: Download Windows binary from releases
    • Docker: docker run --rm -v "$(pwd):/workspace" --workdir /workspace bufbuild/buf
    • Go: go install github.com/bufbuild/buf/cmd/buf@latest
    • NPM: npm install @bufbuild/buf

Core Imports

# CLI binary execution
buf [command] [flags] [arguments]

# Docker usage
docker run --rm -v "$(pwd):/workspace" --workdir /workspace bufbuild/buf [command]

# NPM/Node.js usage
npx @bufbuild/buf [command]

Basic Usage

# Initialize a new buf module
buf config init

# Lint Protocol Buffer files
buf lint

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

# Generate code from proto files
buf generate

# Format proto files
buf format --write

# Build proto files into an image
buf build -o image.bin

# Push module to registry
buf push

# Export proto files
buf export -o exported/

Architecture

Buf is built around several key components:

  • Core Operations: Primary Protocol Buffer tooling (lint, breaking, generate, format, build)
  • Registry Integration: Seamless integration with Buf Schema Registry (BSR) for module management
  • Configuration System: Flexible configuration via buf.yaml, buf.gen.yaml, and buf.work.yaml files
  • Plugin System: Extensible code generation using protoc plugins and templates
  • Input Sources: Support for local files, git repositories, BSR modules, and archives
  • Multi-format Output: Support for various output formats (binary, JSON, text)

Capabilities

Core Protocol Buffer Operations

Essential Protocol Buffer development operations including compilation, validation, and code generation.

# Build proto files into various output formats
buf build [flags] [input]

# Lint proto files with configurable rules
buf lint [flags] [input]

# Check for breaking changes between proto versions
buf breaking [flags] [input] --against [against-input]

# Generate code using protoc plugins and templates
buf generate [flags] [input]

# Format proto files following industry standards
buf format [flags] [input]

Core Operations

Registry Operations

Complete Buf Schema Registry (BSR) integration for centralized schema management, module publishing, and dependency resolution.

# Push a module to the registry
buf push [flags] [input]

# Registry authentication
buf registry login [domain]
buf registry logout [domain]

# Module management
buf registry module create <name>
buf registry module info <module>
buf registry module delete <module>

Registry Operations

Configuration Management

Tools for initializing, managing, and migrating buf configuration files and workspace settings.

# Initialize buf configuration
buf config init [flags]

# List available lint rules
buf config ls-lint-rules

# List available breaking change rules
buf config ls-breaking-rules

# Migrate configuration to latest version
buf config migrate [flags]

Configuration Management

Dependency Management

Manage Protocol Buffer dependencies and workspace configurations.

# Show dependency graph
buf dep graph [flags] [input]

# Update dependencies to latest versions
buf dep update [flags] [input]

# Remove unused dependencies
buf dep prune [flags] [input]

Dependency Management

Utility Operations

Additional utilities for working with Protocol Buffer files and modules.

# Export proto files to another location
buf export [flags] [input] [output]

# Convert messages between formats (JSON, binary, text)
buf convert [flags] --type [type] [input]

# Make RPC requests (gRPC curl functionality)
buf curl [flags] [input] [server]

# List proto files in a module
buf ls-files [flags] [input]

# Show statistics about proto files
buf stats [flags] [input]

Utility Operations

Global Configuration

Common Flags

Available across most commands:

--config string          Override config file path
--disable-symlinks       Disable symlink resolution for security
--error-format string    Error output format (text, json, msvs, junit, github-actions)
--path strings           Include only specified paths
--exclude-path strings   Exclude specific paths from processing

Input Types

Buf supports multiple input sources:

  • Local: File paths, directories
  • Git: Git repositories with branch/tag/commit support (git_repo#branch=main)
  • BSR: Buf Schema Registry modules (buf.build/owner/module[:ref])
  • Archives: tar, tar.gz, zip files
  • Remote: HTTP/HTTPS URLs
  • Stdin: Use - for stdin input

Configuration Files

# buf.yaml - Main module configuration
version: v1
name: buf.build/acme/petapis
deps:
  - buf.build/googleapis/googleapis

# buf.gen.yaml - Code generation template
version: v1
plugins:
  - name: go
    out: gen/go
    opt: paths=source_relative
  - name: go-grpc
    out: gen/go
    opt: paths=source_relative

# buf.work.yaml - Workspace configuration
version: v1
directories:
  - proto
  - vendor-protos

Environment Variables

Key environment variables for configuration:

BUF_TOKEN                    # Authentication token for BSR
BUF_REGISTRY                 # Custom registry URL
BUF_CONFIG_OVERRIDE          # Override config file path
BUF_CACHE_DIR                # Custom cache directory
BUF_INPUT_HTTPS_USERNAME     # HTTPS authentication username
BUF_INPUT_HTTPS_PASSWORD     # HTTPS authentication password
BUF_INPUT_SSH_KEY_FILE       # SSH key file path
BUF_LOG_LEVEL                # Log level (debug, info, warn, error)

Error Handling

Buf provides structured error reporting with multiple output formats:

  • text: Human-readable format (default)
  • json: Machine-readable JSON format
  • msvs: Microsoft Visual Studio format
  • junit: JUnit XML format for CI/CD integration
  • github-actions: GitHub Actions annotations

Exit codes:

  • 0: Success
  • 1: General error
  • 100: Lint or breaking change violations detected

Policy Management

Manage check policies for organizational compliance and governance.

# Push policies to registry
buf policy push [policy]

# Update policy dependencies
buf policy update

# Remove unused policies
buf policy prune

# Registry policy management
buf registry policy create <name>
buf registry policy info <policy>
buf registry policy delete <policy>

Policy Management

Experimental Features

Beta and alpha commands for advanced use cases and experimental functionality with potential for breaking changes.

# Language Server Protocol support
buf beta lsp

# Buf Studio integration  
buf beta studio-agent

# Registry webhooks
buf beta registry webhook create <repo>
buf beta registry webhook list <repo>
buf beta registry webhook delete <webhook>

# Plugin management
buf plugin push <plugin>
buf plugin update
buf plugin prune

# Protoc compatibility
buf alpha protoc [files...]

# Token management
buf alpha registry token get
buf alpha registry token list
buf alpha registry token delete <token>

Experimental Features