Configuration Overview

bz supports two types of configuration:

TOML files - For persistent settings like network mode, cache directory, and registry URL
Starlark files - For registry sync workflows (advanced feature)

Quick Start

Most users only need TOML configuration for basic settings:

[network]
mode = "prefer-offline"           # Use cache when available

[cache]
dir = "~/.cache/bz"

For registry sync workflows, use Starlark configuration in bz.star.

Configuration Types

TOML Configuration

Configure network mode, cache settings, and disabled commands. Used for everyday bz settings.

Learn more

Starlark Configuration

Define registry sync workflows with Starlark. Used for mirroring BCR to internal registries.

Learn more

TOML Configuration

TOML files configure bz’s runtime behavior. Files are loaded from multiple locations with later files overriding earlier ones.

File Locations

Location	Purpose
`/etc/bz/config.toml`	System-wide defaults
`~/.config/bz/config.toml`	User preferences
`.bz.toml`	Project-specific settings

Example

[network]
mode = "prefer-offline"
registry = "https://bcr.bazel.build"
timeout = "30s"

[cache]
dir = "~/.cache/bz"

[commands]
disabled = []

Environment Variables

Variable	Description
`BZ_OFFLINE`	Enable offline mode
`BZ_PREFER_OFFLINE`	Enable prefer-offline mode
`BZ_REGISTRY`	Override registry URL
`BZ_CACHE_DIR`	Override cache directory
`BZ_DISABLE_COMMANDS`	Disable commands (comma-separated)

Full TOML documentation

Starlark Configuration

Starlark files (bz.star) define sync workflows for mirroring modules between registries. This is an advanced feature for organizations maintaining internal registries.

Basic Example

bcr = registry.http("https://bcr.bazel.build")
mirror = registry.file("/path/to/mirror")

sync.workflow(
    name = "sync-all",
    origin = bcr,
    destination = mirror,
    modules = ["rules_go", "rules_python"],
)

Run with:

bz mod sync sync-all

Starlark Documentation

Starlark Basics

Learn the Starlark language basics for writing configurations.

Learn more

Registries

Configure source and destination registries.

Learn more

Publishers

Set up different publishing backends.

Learn more

Transforms

Transform modules as they sync.

Learn more

Configuration Precedence

All configuration is merged in this order (later overrides earlier):

Built-in defaults
System config (/etc/bz/config.toml)
User config (~/.config/bz/config.toml)
Project config (.bz.toml)
Environment variables
CLI flags