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

Registry Operations

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

Capabilities

Authentication

Manage authentication with the Buf Schema Registry.

/**
 * Log in to BSR using browser-based OAuth flow
 * @param domain - Registry domain (default: buf.build)
 */
buf registry login [domain]

# Key flags:
--username string     Username for login
--token-stdin        Read token from stdin instead of browser flow
--prompt             Prompt for credentials interactively

/**
 * Log out from BSR
 * @param domain - Registry domain (default: buf.build)  
 */
buf registry logout [domain]

/**
 * Show current authenticated user information
 */
buf registry whoami

/**
 * Clear registry cache
 */
buf registry cc

Usage Examples:

# Interactive browser login
buf registry login

# Login with username
buf registry login --username myuser

# Login with token from stdin
echo "your-token" | buf registry login --token-stdin

# Login to custom registry
buf registry login custom.registry.com

# Check current user
buf registry whoami

# Logout
buf registry logout

# Clear cache
buf registry cc

Module Management

Create, manage, and configure BSR modules for Protocol Buffer schema distribution.

/**
 * Create a new BSR module
 * @param name - Module name in format owner/module
 */
buf registry module create <owner/module>

# Key flags:
--visibility string       Module visibility (public, private)
--description string      Module description
--url string             Homepage URL
--default-label string   Default label for pushes

/**
 * Show detailed information about a module
 * @param module - Module reference (owner/module[:ref])
 */
buf registry module info <module>

/**
 * Delete a module (irreversible)
 * @param module - Module reference (owner/module)
 */
buf registry module delete <module>

/**
 * Mark a module as deprecated
 * @param module - Module reference (owner/module)
 */
buf registry module deprecate <module>

# Key flags:
--message string         Deprecation message

/**
 * Remove deprecation from a module
 * @param module - Module reference (owner/module)
 */
buf registry module undeprecate <module>

Usage Examples:

# Create public module
buf registry module create acme/petapis --visibility public

# Create private module with description
buf registry module create acme/internal --visibility private \
  --description "Internal APIs" --url https://github.com/acme/apis

# Get module information
buf registry module info acme/petapis
buf registry module info acme/petapis:v1.0.0

# Deprecate module
buf registry module deprecate acme/oldapis \
  --message "Migrated to acme/newapis"

# Remove deprecation
buf registry module undeprecate acme/oldapis

# Delete module (dangerous!)
buf registry module delete acme/unused

Module Commits

Manage individual commits within BSR modules.

/**
 * List commits for a module
 * @param module - Module reference (owner/module)
 */
buf registry module commit list <module>

# Key flags:
--page-size int         Number of commits per page
--page-token string     Page token for pagination
--reverse              List in reverse chronological order

/**
 * Show detailed information about a specific commit
 * @param commit - Commit reference (owner/module:commit-id)
 */
buf registry module commit info <commit>

/**
 * Resolve commit reference to specific commit ID
 * @param module - Module reference with label or commit (owner/module:ref)
 */
buf registry module commit resolve <module>

/**
 * Add a label to an existing commit
 * @param commit - Commit reference (owner/module:commit-id)
 * @param label - Label name to add
 */
buf registry module commit add-label <commit> <label>

Usage Examples:

# List recent commits
buf registry module commit list acme/petapis

# List commits with pagination
buf registry module commit list acme/petapis --page-size 50

# Get commit details
buf registry module commit info acme/petapis:abc123def456

# Resolve label to commit ID
buf registry module commit resolve acme/petapis:v1.0.0
buf registry module commit resolve acme/petapis:latest

# Add label to commit
buf registry module commit add-label acme/petapis:abc123def456 stable

Module Labels

Manage semantic labels for module commits (versions, aliases, etc.).

/**
 * List labels for a module
 * @param module - Module reference (owner/module)
 */
buf registry module label list <module>

# Key flags:
--page-size int         Number of labels per page
--page-token string     Page token for pagination

/**
 * Show detailed information about a specific label
 * @param label - Label reference (owner/module:label)
 */
buf registry module label info <label>

/**
 * Archive a label (hide from default listings)
 * @param label - Label reference (owner/module:label)
 */
buf registry module label archive <label>

/**
 * Unarchive a previously archived label
 * @param label - Label reference (owner/module:label)
 */
buf registry module label unarchive <label>

Usage Examples:

# List all labels
buf registry module label list acme/petapis

# Get label information
buf registry module label info acme/petapis:v1.0.0
buf registry module label info acme/petapis:latest

# Archive old version
buf registry module label archive acme/petapis:v0.9.0

# Unarchive label
buf registry module label unarchive acme/petapis:v0.9.0

Module Settings

Configure module-level settings and policies.

/**
 * Update module settings
 * @param module - Module reference (owner/module)
 */
buf registry module settings update <module>

# Key flags:
--description string      Update module description
--url string             Update homepage URL
--default-label string   Update default label for pushes
--visibility string      Update module visibility (public, private)

Usage Examples:

# Update description
buf registry module settings update acme/petapis \
  --description "Pet store APIs v2"

# Change visibility
buf registry module settings update acme/petapis --visibility private

# Update multiple settings
buf registry module settings update acme/petapis \
  --url https://petstore.example.com \
  --default-label main

Organization Management

Create and manage organizations for collaborative development.

/**
 * Create a new organization
 * @param name - Organization name
 */
buf registry organization create <name>

# Key flags:
--description string     Organization description
--url string            Organization homepage URL

/**
 * Show organization information
 * @param org - Organization name
 */
buf registry organization info <org>

/**
 * Update organization settings
 * @param org - Organization name
 */
buf registry organization update <org>

# Key flags:
--description string     Update description
--url string            Update homepage URL
--name string           Update organization name
--verification-status string Update verification status
--format string         Output format (text, json)

/**
 * Delete organization (must be empty)
 * @param org - Organization name
 */
buf registry organization delete <org>

Usage Examples:

# Create organization
buf registry organization create acme \
  --description "ACME Corporation APIs" \
  --url https://acme.com

# Get organization info
buf registry organization info acme

# Update organization
buf registry organization update acme \
  --description "ACME Corp - Innovation APIs" \
  --url https://innovation.acme.com \
  --verification-status verified

# Delete empty organization
buf registry organization delete unused-org

Plugin Management

Manage protoc plugins in the BSR for code generation.

/**
 * Create a new plugin
 * @param name - Plugin name in format owner/plugin
 */
buf registry plugin create <owner/plugin>

# Key flags:
--visibility string      Plugin visibility (public, private)
--description string     Plugin description
--url string            Plugin homepage URL

/**
 * Show plugin information
 * @param plugin - Plugin reference (owner/plugin[:ref])
 */
buf registry plugin info <plugin>

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

Usage Examples:

# Create plugin
buf registry plugin create acme/go-extra \
  --visibility public \
  --description "Extended Go code generation"

# Get plugin info
buf registry plugin info acme/go-extra

# Delete plugin
buf registry plugin delete acme/unused-plugin

Push Operations

Upload modules to the BSR with versioning and metadata.

/**
 * Push a module to the registry
 * @param input - Proto files, directories, git repos, or archives to push
 */
buf push [flags] [input]

# Key flags:
--label string                Add label to the pushed commit
--create                     Create module if it doesn't exist
--create-visibility string   Visibility when creating module (public, private)
--create-default-label string Default label when creating module
--source-control-url string  Associate with source control URL
--git-metadata              Include git metadata (commit, branch info)
--exclude-unnamed           Don't push modules without names in buf.yaml
--tag string                Create tag on push (deprecated, use --label)
--draft                     Push as draft (deprecated)

Usage Examples:

# Push current directory
buf push

# Push with label
buf push --label v1.2.0

# Push and create module if needed
buf push --create --create-visibility public

# Push with git metadata
buf push --git-metadata --label $(git describe --tags)

# Push with source control association
buf push --source-control-url https://github.com/acme/apis

# Push excluding unnamed modules
buf push --exclude-unnamed

# Push specific directory
buf push proto/

Authentication Methods

Environment Variables

# Primary authentication token
BUF_TOKEN=your-bsr-token

# Registry-specific tokens
BUF_REGISTRY_TOKEN=your-registry-token

# Custom registry URL
BUF_REGISTRY=https://custom.registry.com

Netrc Authentication

# ~/.netrc format for BSR authentication
machine buf.build
login your-username
password your-token

# Custom registry
machine custom.registry.com
login your-username  
password your-token

Interactive Login

# Browser-based OAuth flow (recommended)
buf registry login

# Username/password prompts
buf registry login --prompt

# Token from stdin
echo "your-token" | buf registry login --token-stdin

Module References

Reference Formats

# Basic module reference
buf.build/owner/module

# Module with label (version/tag)
buf.build/owner/module:v1.0.0
buf.build/owner/module:latest
buf.build/owner/module:main

# Module with commit ID
buf.build/owner/module:abc123def456

# Module with draft reference
buf.build/owner/module:draft-abc123

Module Names

# Valid module names (lowercase, alphanumeric, hyphens)
owner/simple-name
organization/my-apis
user/proto-definitions

# Invalid names (uppercase, underscores, special chars)
Owner/Simple-Name      # uppercase not allowed
user/my_apis           # underscores not allowed  
org/apis@v1           # special chars not allowed

Error Handling

Registry operations provide detailed error information:

# Common error scenarios
# Authentication required
Error: authentication required, run 'buf registry login'

# Module not found
Error: module "buf.build/owner/nonexistent" not found

# Permission denied
Error: permission denied for module "buf.build/owner/private"

# Module already exists  
Error: module "buf.build/owner/existing" already exists

# Invalid module name
Error: invalid module name "Owner/Invalid_Name"

Exit Codes

0   # Success
1   # General error (authentication, network, etc.)
2   # Invalid arguments or configuration
3   # Permission denied
4   # Resource not found
5   # Resource already exists

Version

Tile

Files