or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

configuration-management.md core-operations.md dependency-management.md experimental-features.md index.md policy-management.md registry-operations.md utility-operations.md

tile.json

Utility Operations

Additional utilities for working with Protocol Buffer files, modules, and services. These operations provide helper functionality for file management, data conversion, service interaction, and analysis.

Capabilities

File Export

Export Protocol Buffer files from one location to another with filtering and dependency options.

/**
 * Export proto files from input to output location
 * @param input - Proto files, directories, git repos, BSR modules, or archives
 */
buf export [flags] [input]

# Key flags:
--output, -o string         Output directory (required)
--exclude-imports          Don't export imported files
--all                      Export all content including dependencies  
--path strings            Export only files under these paths
--exclude-path strings    Exclude files under these paths
--config string           Configuration file path

Usage Examples:

# Export current directory to output folder
buf export -o exported-protos/

# Export excluding imports
buf export --exclude-imports -o clean-protos/

# Export all content including dependencies
buf export --all -o complete-protos/

# Export specific paths only
buf export --path proto/public -o public-protos/

# Export from BSR module
buf export buf.build/googleapis/googleapis -o googleapis-protos/

# Export from git repository
buf export https://github.com/envoyproxy/envoy.git -o envoy-protos/

Message Conversion

Convert Protocol Buffer messages between different formats (binary, JSON, text).

/**
 * Convert messages between binary, text, and JSON formats
 */
buf convert [flags] --type <message-type> [input]

# Key flags:
--type string              Required. Fully qualified message type
--from string              Input format/source (file, stdin, literal)
--to string                Output destination (file, stdout)
--validate                 Validate message during conversion
--config string            Configuration file path

Usage Examples:

# Convert binary to JSON
buf convert --type acme.petstore.Pet \
  --from pet.binpb --to pet.json

# Convert JSON to binary
buf convert --type acme.petstore.Pet \
  --from pet.json --to pet.binpb

# Convert from stdin to stdout
echo '{"name":"Fluffy","species":"cat"}' | \
buf convert --type acme.petstore.Pet --from - --to -

# Convert with validation
buf convert --type acme.petstore.Pet \
  --from pet.json --to pet.binpb --validate

# Convert text format
buf convert --type acme.petstore.Pet \
  --from pet.txtpb --to pet.json

Supported Formats:

# Input/Output formats
.binpb                         # Binary Protocol Buffer
.json                          # JSON representation
.txtpb                         # Text Protocol Buffer
.yaml                          # YAML representation (limited support)
-                              # Stdin/stdout

RPC Invocation

Make RPC requests to servers using Protocol Buffer definitions (gRPC curl functionality).

/**
 * Invoke RPC endpoints with Protocol Buffer definitions
 * Similar to curl but for gRPC and Connect services
 */
buf curl [flags] [method] [endpoint]

# Key flags:
--data string              Request data (JSON, binary, or text format)
--data-file string         File containing request data
--header strings           HTTP headers to include
--timeout duration         Request timeout
--connect-timeout duration Connection timeout
--http2-prior-knowledge    Use HTTP/2 without negotiation
--insecure                Skip TLS certificate verification
--cacert string           CA certificate file
--cert string             Client certificate file
--key string              Client private key file

Usage Examples:

# Simple gRPC call
buf curl --data '{"name":"Fluffy"}' \
  acme.petstore.PetService/GetPet \
  grpc://localhost:8080

# Call with JSON file
buf curl --data-file pet.json \
  acme.petstore.PetService/CreatePet \
  grpc://localhost:8080

# HTTP/Connect call
buf curl --data '{"query":"cats"}' \
  acme.petstore.PetService/SearchPets \
  https://api.petstore.com/v1

# With custom headers
buf curl --header "Authorization: Bearer token123" \
  --data '{"id":"123"}' \
  acme.petstore.PetService/GetPet \
  grpc://api.petstore.com:443

# With TLS configuration
buf curl --cacert ca.pem --cert client.pem --key client.key \
  --data '{"name":"Spot"}' \
  acme.petstore.PetService/CreatePet \
  grpc://secure.petstore.com:443

File Listing

List all Protocol Buffer files in a module or input source.

/**
 * List all proto files for the given input
 * @param input - Proto files, directories, git repos, BSR modules, or archives
 */
buf ls-files [flags] [input]

# Key flags:
--config string           Configuration file path
--path strings           List only files under these paths
--exclude-path strings   Exclude files under these paths
--include-imports        Include imported files in listing
--as-file-paths-to-generate  Output as file paths for generation
--disable-symlinks       Disable symlink resolution

Usage Examples:

# List files in current directory
buf ls-files

# List files in specific paths
buf ls-files --path proto/public --path proto/admin

# List including imports
buf ls-files --include-imports

# List files from BSR module
buf ls-files buf.build/googleapis/googleapis

# List files from git repository
buf ls-files https://github.com/grpc-ecosystem/grpc-gateway.git

# List excluding certain paths
buf ls-files --exclude-path proto/internal

Statistics

Show statistics and analysis about Protocol Buffer files and modules.

/**
 * Display statistics about proto files and modules
 * @param input - Proto files, directories, git repos, BSR modules, or archives
 */
buf stats [flags] [input]

# Key flags:
--config string           Configuration file path
--format string          Output format (text, json)
--path strings           Analyze only files under these paths
--exclude-path strings   Exclude files under these paths

Usage Examples:

# Show statistics for current directory
buf stats

# Show JSON statistics
buf stats --format json

# Statistics for specific paths
buf stats --path proto/public

# Statistics for BSR module
buf stats buf.build/googleapis/googleapis

# Statistics excluding test files
buf stats --exclude-path proto/test

Statistics Output:

# Text format example
Files: 42
Messages: 156
Services: 8
RPCs: 73
Enums: 24
Fields: 1,247
Extensions: 3

# JSON format example
{
  "files": 42,
  "messages": 156,
  "services": 8,
  "rpcs": 73,
  "enums": 24,
  "fields": 1247,
  "extensions": 3,
  "dependencies": {
    "direct": 3,
    "transitive": 12
  }
}

Message Conversion Details

Type Resolution

Converting messages requires fully qualified type names:

# Fully qualified message types
acme.petstore.Pet                    # Message in package
acme.petstore.v1.Pet                # Versioned package
google.protobuf.Timestamp           # Well-known type
acme.petstore.Pet.Address           # Nested message

Format Examples

Examples of message formats supported by conversion:

# JSON format
{
  "name": "Fluffy",
  "species": "cat",
  "age": 3,
  "vaccinated": true,
  "tags": ["indoor", "friendly"]
}

# Text format (.txtpb)
name: "Fluffy"
species: "cat"  
age: 3
vaccinated: true
tags: "indoor"
tags: "friendly"

# Binary format (.binpb)
# Binary Protocol Buffer data (not human readable)

RPC Invocation Details

Supported Protocols

Buf curl supports multiple RPC protocols:

# gRPC over HTTP/2
grpc://host:port/                   # Plaintext gRPC
grpcs://host:port/                  # TLS-encrypted gRPC

# Connect protocol  
https://host/path                   # Connect over HTTPS
http://host/path                    # Connect over HTTP

# gRPC-Web
https://host/path                   # gRPC-Web over HTTPS

Authentication

Various authentication methods for RPC calls:

# Bearer token authentication
--header "Authorization: Bearer token123"

# API key authentication
--header "X-API-Key: your-api-key"

# Custom authentication headers
--header "X-Custom-Auth: custom-value"

# Client certificate authentication
--cert client.pem --key client.key

# Basic authentication (HTTP)
--header "Authorization: Basic $(echo -n 'user:pass' | base64)"

Request Data Sources

Multiple ways to provide request data:

# Inline JSON data
--data '{"field":"value"}'

# From file
--data-file request.json
--data-file request.binpb
--data-file request.txtpb

# From stdin
echo '{"field":"value"}' | buf curl --data-file - ...

# Empty request (for RPCs with no parameters)
buf curl method endpoint  # No --data flag needed

File Operations

Export Filtering

Advanced filtering options for file export:

# Path-based filtering
--path proto/public                 # Include only public APIs
--path proto/v1 --path proto/v2    # Multiple version paths
--exclude-path proto/internal       # Exclude internal APIs
--exclude-path proto/test          # Exclude test files

# Import filtering
--exclude-imports                   # Don't export dependencies
--all                              # Export everything including deps

# Combined filtering
buf export --path proto/public --exclude-imports -o clean-public/

File Listing Options

Detailed file listing with metadata:

# Basic listing
proto/user/user.proto
proto/order/order.proto
proto/common/types.proto

# With path filtering
buf ls-files --path proto/user
# Output:
proto/user/user.proto
proto/user/user_service.proto

# Including imports shows dependency files
buf ls-files --include-imports
# Output includes files from dependencies

Error Handling

Common utility operation errors:

# Export errors
Error: output directory already exists and is not empty
Solution: Use different output path or clean existing directory

# Conversion errors  
Error: unknown message type "invalid.Type"
Solution: Verify message type exists in proto files

Error: failed to parse JSON input
Solution: Check JSON syntax and field names

# RPC errors
Error: connection refused
Solution: Verify server is running and endpoint is correct

Error: unknown service method
Solution: Check service and method names in proto definition

# File listing errors
Error: no proto files found in input
Solution: Verify input path contains .proto files

Exit Codes

0   # Success
1   # General error (file not found, network error, etc.)
2   # Invalid arguments or configuration  
3   # Conversion or parsing error
4   # RPC invocation error
5   # Authentication or permission error

Integration Examples

CI/CD Pipeline Usage

Using utilities in automated workflows:

# Export APIs for documentation generation
buf export --path proto/public -o docs/protos/

# Convert test data for integration tests
buf convert --type test.Message \
  --from testdata.json --to testdata.binpb

# Health check RPC services
buf curl health.HealthService/Check grpc://service:8080

# Analyze API complexity
buf stats --format json > api-metrics.json

Development Workflow

Common development tasks:

# Extract protos from vendor dependencies
buf export buf.build/googleapis/googleapis -o vendor/googleapis/

# Test message serialization
buf convert --type MyMessage --from test.json --to test.binpb --validate

# Debug RPC services locally
buf curl --data '{"debug":true}' \
  debug.DebugService/GetInfo \
  grpc://localhost:9090

# Monitor API growth over time
buf stats > stats-$(date +%Y%m%d).txt

Version

Tile

Files