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

core-operations.mddocs/

Core Protocol Buffer Operations

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

Capabilities

Build Operation

Compile Protocol Buffer files into various output formats including FileDescriptorSet, JSON, and binary images.

/**
 * 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

Usage Examples:

# 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 Operation

Run linting on Protocol Buffer files using 40+ configurable rules to enforce design patterns and best practices.

/**
 * 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

Usage Examples:

# 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

Common Lint Rules:

  • ENUM_ZERO_VALUE_SUFFIX: Enum zero values should have a standard suffix
  • FIELD_LOWER_SNAKE_CASE: Field names should be lower_snake_case
  • MESSAGE_PASCAL_CASE: Message names should be PascalCase
  • PACKAGE_LOWER_SNAKE_CASE: Package names should be lower.snake.case
  • RPC_PASCAL_CASE: RPC names should be PascalCase
  • SERVICE_PASCAL_CASE: Service names should be PascalCase

Breaking Change Detection

Verify no breaking changes have been made by comparing against a previous version with 53+ compatibility rules.

/**
 * 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

Usage Examples:

# 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

Breaking Change Categories:

  • Wire-level: Changes affecting serialization compatibility
  • Source-level: Changes affecting generated code compatibility
  • JSON-level: Changes affecting JSON representation compatibility

Code Generation

Generate code from Protocol Buffer definitions using protoc plugins and templates.

/**
 * 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

Usage Examples:

# 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

Template Configuration (buf.gen.yaml):

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 Operation

Format Protocol Buffer files following industry standards with automatic indentation and style fixes.

/**
 * 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

Usage Examples:

# 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/

Formatting Rules:

  • Consistent indentation (2 spaces)
  • Proper field alignment
  • Standardized comment formatting
  • Sorted imports and options
  • Consistent spacing around operators

Types and Interfaces

Input Sources

All core operations support these input types:

# 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
-

Output Formats

# 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 Handling

All core operations support structured error reporting:

# 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

Exit Codes

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