Experimental Features

/**
 * Start Language Server Protocol server for editor integration
 */
buf beta lsp [flags]

# Key flags:
--pipe                   Use UNIX socket instead of stdio

/**
 * Show BSR pricing information and cost estimates
 */
buf beta price [flags]

/**
 * Run Buf Studio agent for browser-based Protocol Buffer exploration
 * Provides HTTP(S) proxy server with comprehensive TLS configuration
 */
buf beta studio-agent [flags]

# Key flags:
--bind string             Bind address (default: 127.0.0.1)
--port int               Port to listen on (default: 8080)
--origin strings         Allowed CORS origins
--disallowed-header strings Headers to disallow forwarding
--forward-header strings  Additional headers to forward
--ca-cert string         CA certificate file path
--client-cert string     Client certificate file path
--client-key string      Client private key file path
--server-cert string     Server certificate file path
--server-key string      Server private key file path
--private-network        Allow private network access

/**
 * Run v1beta1 plugin execution
 */
buf beta buf-plugin-v1beta1 [flags]

# Key flags:
--protocol string        Plugin protocol (grpc, stdio)
--spec string           Plugin specification file
--format string         Output format (text, json)

/**
 * Run v1 plugin execution  
 */
buf beta buf-plugin-v1 [flags]

# Key flags:
--protocol string        Plugin protocol (grpc, stdio)
--spec string           Plugin specification file
--format string         Output format (text, json)

/**
 * Run v2 plugin execution
 */
buf beta buf-plugin-v2 [flags]

# Key flags:
--protocol string        Plugin protocol (grpc, stdio)
--spec string           Plugin specification file
--format string         Output format (text, json)

# Start LSP server for IDE integration
buf beta lsp

# Start LSP with pipe communication
buf beta lsp --pipe

# Show pricing information
buf beta price

# Run Studio agent
buf beta studio-agent

# Execute plugins with different versions
buf beta buf-plugin-v1 --plugin-config config.yaml
buf beta buf-plugin-v2 --plugin-config config.yaml

/**
 * Create webhook for repository events
 * @param repo - Repository reference (owner/repo)
 */
buf beta registry webhook create <repo>

# Key flags:
--url string            Webhook endpoint URL
--events strings        Events to trigger webhook (push, label, etc.)
--secret string         Webhook secret for validation

/**
 * Delete existing webhook
 * @param webhook - Webhook ID or reference
 */
buf beta registry webhook delete <webhook>

/**
 * List webhooks for repository
 * @param repo - Repository reference (owner/repo)
 */
buf beta registry webhook list <repo>

/**
 * Push plugin to registry (beta implementation)
 * @param plugin - Plugin directory or archive
 */
buf beta registry plugin push <plugin>

# Key flags:
--label string          Plugin version label
--create               Create plugin if it doesn't exist
--visibility string    Plugin visibility (public, private)

/**
 * Delete plugin from registry (beta implementation)
 * @param plugin - Plugin reference (owner/plugin)
 */
buf beta registry plugin delete <plugin>

# Create webhook for push events
buf beta registry webhook create acme/apis \
  --url https://ci.acme.com/webhook \
  --events push,label \
  --secret webhook-secret-123

# List webhooks
buf beta registry webhook list acme/apis

# Delete webhook
buf beta registry webhook delete webhook-abc123

# Push plugin (beta)
buf beta registry plugin push ./my-plugin \
  --label v1.0.0 --create --visibility public

# Delete plugin (beta)
buf beta registry plugin delete acme/my-plugin

/**
 * Protoc compatibility wrapper for legacy workflows
 */
buf alpha protoc [flags] [files...]

# Provides protoc-compatible interface for buf operations
# Allows gradual migration from protoc to buf

/**
 * Get user authentication token
 */
buf alpha registry token get

/**
 * List user authentication tokens
 */
buf alpha registry token list

# Key flags:
--format string         Output format (text, json)
--page-size int        Number of tokens per page

/**
 * Delete user authentication token
 * @param token - Token ID or name
 */
buf alpha registry token delete <token>

# Use protoc compatibility mode
buf alpha protoc --go_out=gen/ --go-grpc_out=gen/ proto/*.proto

# Get current token
buf alpha registry token get

# List all tokens
buf alpha registry token list --format json

# Delete specific token
buf alpha registry token delete old-token-123

/**
 * Push plugin to BSR for distribution
 * @param plugin - Plugin directory, archive, or reference
 */
buf plugin push [flags] [plugin]

# Key flags:
--label string          Version label for plugin
--create               Create plugin if it doesn't exist
--create-visibility string  Visibility when creating (public, private)
--source-control-url string  Associate with source control

/**
 * Update plugin dependencies to latest versions
 */
buf plugin update [flags]

# Key flags:
--only strings         Update only specified plugins
--strategy string      Update strategy (latest, minor, patch)

/**
 * Remove unused plugins from configuration
 */
buf plugin prune [flags]

# Key flags:
--write               Write changes to configuration file
--dry-run             Show what would be removed

# Push plugin to registry
buf plugin push ./my-protoc-plugin \
  --label v2.1.0 \
  --create \
  --create-visibility public

# Update all plugin dependencies
buf plugin update

# Update specific plugins only
buf plugin update --only buf.build/grpc/go

# Remove unused plugins
buf plugin prune --write

# Dry run to see what would be pruned
buf plugin prune --dry-run

# Push plugin with beta registry command
buf beta registry plugin push ./my-plugin \
  --label v1.0.0 --visibility public

# Delete plugin (beta)
buf beta registry plugin delete acme/my-plugin

/**
 * Protoc plugin for linting Protocol Buffers
 * Used via protoc with --buf-lint_out flag
 */
protoc --buf-lint_out=. --buf-lint_opt=config-path=buf.yaml proto/*.proto

# Configuration via plugin parameter (JSON/YAML format):
{
  "lint": {
    "use": ["DEFAULT"],
    "except": ["ENUM_ZERO_VALUE_SUFFIX"]
  }
}

# Basic linting via protoc
protoc --buf-lint_out=. proto/*.proto

# With custom configuration
protoc --buf-lint_out=. \
  --buf-lint_opt='{"lint":{"use":["DEFAULT","COMMENTS"]}}' \
  proto/*.proto

# Using configuration file
protoc --buf-lint_out=. \
  --buf-lint_opt=config-path=custom-buf.yaml \
  proto/*.proto

/**
 * Protoc plugin for breaking change detection
 * Used via protoc with --buf-breaking_out flag
 * Requires against_input parameter for comparison
 */
protoc --buf-breaking_out=. \
  --buf-breaking_opt='{"against_input":"previous-version/"}' \
  proto/*.proto

# Required configuration parameters:
{
  "against_input": "path/to/previous/version",
  "breaking": {
    "use": ["FILE"],
    "except": ["FIELD_SAME_JSON_NAME"]
  }
}

# Basic breaking change detection
protoc --buf-breaking_out=. \
  --buf-breaking_opt='{"against_input":"../v1.0.0/proto/"}' \
  proto/*.proto

# With custom breaking rules
protoc --buf-breaking_out=. \
  --buf-breaking_opt='{
    "against_input": "previous/",
    "breaking": {
      "use": ["FILE", "PACKAGE"],
      "except": ["FIELD_SAME_JSON_NAME"]
    }
  }' \
  proto/*.proto

# Using git reference for comparison
protoc --buf-breaking_out=. \
  --buf-breaking_opt='{"against_input":".git#branch=main"}' \
  proto/*.proto

# Stability guarantees
Stable (buf <command>)          # No breaking changes within major versions
Beta (buf beta <command>)       # May have breaking changes, actively developed
Alpha (buf alpha <command>)     # Experimental, may be removed or changed significantly

# Production usage guidelines
✅ Stable commands             # Safe for production use
⚠️  Beta commands              # Use with caution, test thoroughly
❌ Alpha commands              # Development/testing only, not for production

# Common upgrade paths
buf alpha protoc                # Legacy protoc compatibility
     ↓ migrate to
buf <standard-commands>         # Native buf commands

buf beta <feature>              # Beta feature testing
     ↓ promote to  
buf <feature>                   # Stable feature (when promoted)

/**
 * Generate markdown documentation for buf commands
 * Hidden command for generating comprehensive CLI documentation
 */
buf webpages [flags]

# Key flags:
--config string           Configuration file path
--include-front-matter    Include YAML front matter in generated docs

# Generate documentation for all commands
buf webpages

# Generate with YAML front matter
buf webpages --include-front-matter

# Generate with custom config
buf webpages --config custom-buf.yaml

# Beta/Alpha specific errors
Error: beta feature requires opt-in flag
Solution: Add --enable-beta-features flag

Error: alpha command not available in this build
Solution: Use development build or wait for feature promotion

Warning: beta feature may change in future versions
Solution: Pin to specific buf version for stability

# Plugin-specific errors  
Error: plugin not found in registry
Solution: Verify plugin name and check authentication

Error: plugin version conflict
Solution: Use buf plugin update to resolve conflicts

0   # Success
1   # General error
2   # Feature not available/disabled
3   # Beta/Alpha feature warning (with --strict-mode)
100 # Plugin validation errors