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

configuration-management.mddocs/

Configuration Management

Tools for initializing, managing, and migrating buf configuration files and workspace settings. Buf uses several configuration files to manage module settings, dependencies, code generation, and workspace layouts.

Capabilities

Configuration Initialization

Initialize buf configuration files for new projects.

/**
 * Initialize buf configuration files
 * Creates buf.yaml with basic module configuration
 */
buf config init [flags]

# Key flags:
--type string        Module type (default: standard module)
--name string        Module name (format: buf.build/owner/module)
--dep strings        Add dependencies to the module
--doc               Generate documentation comments in config

Usage Examples:

# Initialize basic configuration
buf config init

# Initialize with module name
buf config init --name buf.build/acme/petapis

# Initialize with dependencies
buf config init --name buf.build/acme/apis \
  --dep buf.build/googleapis/googleapis \
  --dep buf.build/grpc-ecosystem/grpc-gateway

# Initialize with documentation
buf config init --doc

Generated buf.yaml:

version: v1
name: buf.build/acme/petapis
deps:
  - buf.build/googleapis/googleapis
lint:
  use:
    - DEFAULT
breaking:
  use:
    - FILE

Configuration Migration

Migrate existing configuration files to newer versions and formats.

/**
 * Migrate configuration files to latest version
 * Supports v1beta1 to v1 migration and future versions
 */
buf config migrate [flags]

# Key flags:
--config string      Path to configuration file to migrate (default: buf.yaml)
--write             Write migrated config back to file
--diff              Show diff of changes

Usage Examples:

# Show migration preview
buf config migrate

# Migrate and write changes
buf config migrate --write

# Show detailed diff
buf config migrate --diff

# Migrate specific config file
buf config migrate --config legacy-buf.yaml --write

Rule Inspection

List available lint and breaking change rules for configuration.

/**
 * List all available lint rules with descriptions
 */
buf config ls-lint-rules

# Key flags:
--all               Show all rules including deprecated ones
--config string     Show rules from specific configuration
--format string     Output format (text, json)

/**
 * List all available breaking change rules with descriptions  
 */
buf config ls-breaking-rules

# Key flags:
--all               Show all rules including deprecated ones
--config string     Show rules from specific configuration
--format string     Output format (text, json)

Usage Examples:

# List lint rules
buf config ls-lint-rules

# List breaking rules with JSON output
buf config ls-breaking-rules --format json

# Show all rules including deprecated
buf config ls-lint-rules --all

# Show rules from specific config
buf config ls-lint-rules --config custom-buf.yaml

Module Inspection

List and inspect modules in the current workspace.

/**
 * List all modules in the current workspace
 * Shows module names, paths, and dependency information
 */
buf config ls-modules [flags]

# Key flags:
--format string     Output format (text, json)
--config string     Path to workspace configuration file

Usage Examples:

# List modules in workspace
buf config ls-modules

# List with JSON output
buf config ls-modules --format json

# List from specific workspace config
buf config ls-modules --config custom-buf.work.yaml

Configuration Files

buf.yaml - Module Configuration

Main configuration file for individual Protocol Buffer modules.

# buf.yaml structure
version: v1                    # Configuration version (required)
name: buf.build/owner/module   # Module name for BSR (optional)

# Dependencies from BSR or local paths
deps:
  - buf.build/googleapis/googleapis
  - buf.build/grpc-ecosystem/grpc-gateway

# Build configuration
build:
  excludes:                    # Exclude files/directories from build
    - vendor/
    - tmp/

# Lint configuration  
lint:
  use:                        # Rule categories to use
    - DEFAULT                 # Default rule set
    - COMMENTS               # Comment-related rules
  except:                     # Individual rules to disable
    - ENUM_ZERO_VALUE_SUFFIX
  ignore:                     # Files to ignore for linting
    - proto/legacy/
  ignore_only:               # Ignore specific rules for specific files
    ENUM_ZERO_VALUE_SUFFIX:
      - proto/v1/

# Breaking change detection configuration
breaking:
  use:                        # Rule categories to use
    - FILE                    # File-level compatibility rules
    - PACKAGE                 # Package-level compatibility rules
  except:                     # Individual rules to disable
    - FIELD_SAME_JSON_NAME
  ignore:                     # Files to ignore for breaking detection
    - proto/experimental/
  ignore_only:               # Ignore specific rules for specific files
    FIELD_SAME_JSON_NAME:
      - proto/v1beta/

buf.gen.yaml - Code Generation Template

Configuration for code generation using protoc plugins.

# buf.gen.yaml structure  
version: v1                    # Template version (required)

# Plugin configurations
plugins:
  - name: go                   # Plugin name (local or BSR)
    out: gen/go               # Output directory
    opt:                      # Plugin options
      - paths=source_relative
      - module=github.com/acme/apis
  
  - name: go-grpc             # gRPC Go plugin
    out: gen/go
    opt: paths=source_relative
    
  - name: buf.build/grpc-ecosystem/gateway:v2.15.2  # BSR plugin
    out: gen/go
    opt:
      - paths=source_relative
      - grpc_api_configuration=gateway.yaml

# Generation options
options:
  cc_enable_arenas: true      # C++ arena allocation
  java_multiple_files: true   # Java multiple files per package
  optimize_for: SPEED         # Optimization mode

# Input filtering
types:                        # Generate only specific types
  - google.protobuf.Empty
  - acme.petstore.Pet
  
exclude_types:                # Exclude specific types
  - acme.internal.DebugInfo

buf.work.yaml - Workspace Configuration

Configuration for multi-module workspaces.

# buf.work.yaml structure
version: v1                   # Workspace version (required)

# Module directories in workspace
directories:
  - proto/public              # Public APIs
  - proto/internal            # Internal APIs  
  - vendor/googleapis         # Vendored dependencies
  
# Workspace-level dependencies
deps:
  - buf.build/grpc-ecosystem/grpc-gateway

buf.lock - Dependency Lock File

Auto-generated file containing resolved dependency versions (similar to package-lock.json).

# buf.lock structure (auto-generated)
version: v1

deps:
  - remote: buf.build
    owner: googleapis
    repository: googleapis
    commit: 62f35882210941b06d351afc3c5a4b3233d40b05
    digest: shake256:1234567890abcdef...
    
  - remote: buf.build  
    owner: grpc-ecosystem
    repository: grpc-gateway
    commit: a7f35faf610eaefb2d72a93b7697ea04d1d5fe17
    digest: shake256:abcdef1234567890...

Configuration Rules

Lint Rules

Categories and individual rules for Protocol Buffer linting:

# Rule categories
DEFAULT                       # Standard linting rules
MINIMAL                      # Minimal rule set
BASIC                        # Basic compatibility rules
COMMENTS                     # Comment-related rules
UNARY_RPC                    # Unary RPC specific rules

# Individual lint rules (examples)
ENUM_ZERO_VALUE_SUFFIX       # Enum zero value naming
FIELD_LOWER_SNAKE_CASE       # Field naming convention  
MESSAGE_PASCAL_CASE          # Message naming convention
PACKAGE_LOWER_SNAKE_CASE     # Package naming convention
RPC_PASCAL_CASE              # RPC method naming
SERVICE_PASCAL_CASE          # Service naming convention

Breaking Change Rules

Categories and rules for breaking change detection:

# Rule categories  
FILE                         # File-level compatibility
PACKAGE                      # Package-level compatibility  
WIRE                         # Wire format compatibility
WIRE_JSON                    # Wire + JSON compatibility

# Individual breaking rules (examples)
FIELD_SAME_TYPE              # Field type consistency
FIELD_SAME_JSON_NAME         # JSON field name consistency
MESSAGE_NO_DELETE            # Message deletion detection
ENUM_VALUE_NO_DELETE         # Enum value deletion detection
RPC_SAME_REQUEST_TYPE        # RPC request type consistency

Environment Variables

Configuration-related environment variables:

# Configuration overrides
BUF_CONFIG_OVERRIDE          # Override config file path
BUF_WORK_CONFIG_OVERRIDE     # Override workspace config path

# Cache and data directories
BUF_CACHE_DIR                # Custom cache directory
BUF_DATA_DIR                 # Custom data directory

# Input configuration
BUF_INPUT_CONFIG             # Override input configuration

Migration Patterns

v1beta1 to v1 Migration

Common migration patterns when upgrading configurations:

# v1beta1 format (deprecated)
version: v1beta1
build:
  roots:
    - proto
lint:
  rules:
    - DEFAULT
breaking:
  rules:
    - FILE_SAME_PACKAGE

# v1 format (current)
version: v1
build:
  excludes:              # Changed from roots to excludes
    - vendor/
lint:
  use:                   # Changed from rules to use
    - DEFAULT
breaking:
  use:                   # Changed from rules to use  
    - FILE

Workspace Migration

Converting single-module to workspace:

# Before: Single buf.yaml
version: v1
build:
  roots:
    - proto/public
    - proto/internal

# After: buf.work.yaml + multiple buf.yaml files
# buf.work.yaml
version: v1
directories:
  - proto/public
  - proto/internal

# proto/public/buf.yaml
version: v1
name: buf.build/acme/public

# proto/internal/buf.yaml  
version: v1
name: buf.build/acme/internal

Error Handling

Configuration errors and common solutions:

# Common configuration errors
Error: buf.yaml uses unsupported version v1beta1
Solution: Run 'buf config migrate --write'

Error: module name "invalid_name" is not valid
Solution: Use format "buf.build/owner/module" with lowercase and hyphens

Error: circular dependency detected  
Solution: Review deps in buf.yaml and remove circular references

Error: workspace contains overlapping modules
Solution: Ensure directories in buf.work.yaml don't overlap