CLI Reference

bz provides commands for managing Bazel module dependencies, analyzing your dependency graph, scanning for security issues, and preparing for offline/air-gapped environments.

Global Flags

These flags are available for all commands:

Flag	Description
-q, --quiet	Reduce output, only show errors and essential info
--no-color	Disable colored output (auto-detected when not a TTY)
--offline	Disable all network access, use cache only
--prefer-offline	Prefer cached data, fallback to network if needed
--registry <url>	Override the default registry URL
-h, --help	Show help for any command
-v, --version	Show version information (on root command)

bz mod list --quiet              # minimal output
bz mod info rules_go --no-color  # no ANSI colors
bz mod list --offline            # cache only
bz mod outdated --prefer-offline # cache first
bz mod search --registry=https://my.registry rules_go

Command Categories

Module Management

init, mod add, mod rm, mod list, mod info, mod update, mod outdated, mod search, mod sync

Dependency Analysis

mod graph, mod stats, mod why

Security & Compliance

audit, mod licenses, sbom

Cache & Offline

cache download, cache stats, cache verify, cache clear

Utilities

doctor, registry ping, completion, version

---

Module Initialization

bz init

Initialize a new Bazel module by creating a MODULE.bazel file.

bz init                          # use directory name as module name
bz init --name=my_module         # set module name
bz init --name=foo --version=1.0.0
bz init --force                  # overwrite existing MODULE.bazel

Flag	Description
--name	Module name (defaults to directory name)
--version	Initial module version (default: 0.0.0)
--force	Overwrite existing MODULE.bazel

---

Module Management

bz mod add

Add one or more dependencies to MODULE.bazel.

bz mod add rules_go@0.50.1
bz mod add rules_go@0.50.1 rules_python@0.35.0
bz mod add --dev gazelle@0.38.0

Flag	Description
--dev	Add as a dev dependency

Tip

Specify version with @version syntax. Without a version, the latest stable version is used.

bz mod rm

Remove dependencies from MODULE.bazel.

bz mod rm rules_go
bz mod rm rules_go rules_python
bz mod rm --dry-run rules_go

Flag	Description
--dry-run	Show what would be removed without making changes

bz mod list

List dependencies in MODULE.bazel.

bz mod list
bz mod list --all     # include extensions, overrides, toolchains
bz mod list --json

Flag	Description
-a, --all	Show all contents (extensions, overrides, etc.)
--json	Output as JSON

JSON output format:

{
  "dependencies": [
    {"name": "rules_go", "version": "0.50.1", "dev_dependency": false},
    {"name": "gazelle", "version": "0.38.0", "dev_dependency": true}
  ]
}

bz mod info

Show information about a module from the registry.

bz mod info rules_go            # show metadata and all versions
bz mod info rules_go@0.50.1     # show specific version details
bz mod info rules_go --json

Flag	Description
--json	Output as JSON

bz mod update

Update dependencies to latest stable versions.

bz mod update                    # update all dependencies
bz mod update rules_go           # update specific module
bz mod update rules_go gazelle   # update multiple modules
bz mod update --dry-run          # preview changes

Flag	Description
--dry-run	Show what would be updated without making changes

bz mod outdated

Check all dependencies for newer versions.

bz mod outdated
bz mod outdated --json

Flag	Description
--json	Output as JSON

Example output:

Module      Current  Latest
------      -------  ------
rules_go    0.49.0   0.50.1
gazelle     0.37.0   0.38.0

bz mod search

Search for modules in the registry.

bz mod search rules_go
bz mod search python
bz mod search protobuf -v        # show version info
bz mod search grpc -n 5          # limit to 5 results

Flag	Description
-v, --verbose	Show version info for each result
-n, --limit	Maximum number of results (default: 20)

bz mod sync

Sync modules from a source registry to a destination based on a workflow defined in bz.star configuration.

bz mod sync mirror-essential           # run a workflow
bz mod sync mirror-essential --dry-run # preview what would be synced
bz mod sync --list                     # list available workflows

Flag	Description
-c, --config	Path to config file (default: bz.star)
--dry-run	Show what would be synced without making changes
-l, --list	List available workflows
--modules	Override modules to sync (comma-separated)
-v, --verbose	Print detailed progress

See Configuration for details on writing Starlark sync workflows.

---

Dependency Analysis

bz mod graph

Display the dependency graph of your Bazel module.

bz mod graph                     # ASCII tree output
bz mod graph --format=dot        # Graphviz DOT format
bz mod graph --format=mermaid    # Mermaid diagram
bz mod graph --format=json       # JSON structure
bz mod graph --json              # shortcut for --format=json
bz mod graph --depth=2           # limit depth

Flag	Description
--format	Output format: ascii (default), dot, json, mermaid
--json	Shortcut for --format=json
--depth	Maximum depth to traverse (0 = unlimited)

Example ASCII output:

my_project
├── rules_go@0.50.1
│   ├── bazel_skylib@1.5.0
│   └── platforms@0.0.8
└── rules_python@0.35.0
    └── bazel_skylib@1.5.0

Generate visualization:

bz mod graph --format=dot | dot -Tpng -o deps.png

bz mod stats

Display statistics about module dependencies.

bz mod stats
bz mod stats --json

Flag	Description
--json	Output as JSON

Example output:

Dependency Statistics:
  Direct dependencies:     5
  Transitive dependencies: 12
  Total modules:           17
  Max depth:               4
  Dev dependencies:        2

bz mod why

Show the dependency path(s) that bring a module into your project.

bz mod why protobuf              # why is protobuf included?
bz mod why protobuf --all        # show all paths, not just shortest
bz mod why protobuf --json

Flag	Description
--all	Show all paths (default: shortest paths only)
--json	Output as JSON

Example output:

protobuf is a direct dependency

protobuf is required by:
  my_project -> rules_go@0.50.1 -> protobuf@25.3
  my_project -> protobuf@25.3

---

Security & Compliance

bz audit

Scan dependencies for security vulnerabilities using the OSV database.

bz audit                         # scan all dependencies
bz audit --json                  # output as JSON
bz audit --severity=high         # only high/critical vulnerabilities
bz audit --fix                   # show suggested updates
bz audit --ecosystem=Go          # specify ecosystem manually

Flag	Description
--json	Output as JSON
--severity	Minimum severity to report: critical, high, medium, low
--fix	Show suggested updates to fix vulnerabilities
--ecosystem	OSV ecosystem to query (e.g., Go, PyPI, crates.io, npm, Maven)

Note

OSV does not have a “Bazel” ecosystem. bz maps known Bazel modules to their underlying ecosystems:

• rules_go, gazelle → Go
• rules_python → PyPI
• rules_rust → crates.io
• rules_nodejs → npm
• rules_java → Maven

Modules without a known mapping will be skipped. Use --ecosystem to manually specify.

Example output:

Module      Version  ID              Severity  Summary
------      -------  --              --------  -------
protobuf    25.3     GHSA-xxxx-xxxx  HIGH      Buffer overflow in...

Suggested fixes:
  bz mod update protobuf --version=25.4

The command returns a non-zero exit code if vulnerabilities are found.

bz mod licenses

Display license information for all dependencies.

bz mod licenses                          # list all licenses
bz mod licenses --json                   # output as JSON
bz mod licenses --summary                # show license counts only
bz mod licenses --check --deny=GPL-3.0   # check for denied licenses
bz mod licenses --check --allow=MIT,Apache-2.0

Flag	Description
--json	Output as JSON
--summary	Show license summary only
--check	Check licenses against policy (requires --allow or --deny)
--allow	Comma-separated list of allowed licenses
--deny	Comma-separated list of denied licenses

Example output:

Module          Version  License
------          -------  -------
bazel_skylib    1.5.0    Apache-2.0
rules_go        0.50.1   Apache-2.0
rules_python    0.35.0   Apache-2.0

Summary: 3 Apache-2.0

Policy checking:

# Fail if any GPL licenses are found
bz mod licenses --check --deny=GPL-2.0,GPL-3.0,LGPL-3.0

# Only allow specific licenses
bz mod licenses --check --allow=MIT,Apache-2.0,BSD-3-Clause

bz sbom

Generate a Software Bill of Materials (SBOM) for your Bazel module.

bz sbom                          # SPDX 2.3 JSON to stdout
bz sbom --format=cyclonedx       # CycloneDX 1.4 JSON
bz sbom --output=sbom.json       # write to file
bz sbom --include-transitive=false

Flag	Description
--format	Output format: spdx (default), cyclonedx
--output	Output file path (default: stdout)
--include-transitive	Include transitive dependencies (default: true)
--registry	Registry URL

Supported formats:

• SPDX 2.3 - ISO/IEC 5962:2021 standard
• CycloneDX 1.4 - OWASP standard

---

Cache Management

For air-gapped environments, bz provides cache management commands.

bz cache download

Download modules and their transitive dependencies to the local cache.

bz cache download                    # cache deps from MODULE.bazel
bz cache download rules_go gazelle   # cache specific modules
bz cache download rules_go@0.50.1    # cache specific version
bz cache download --all              # cache ALL modules (large!)

Flag	Description
--all	Download ALL modules from registry (warning: very large)
--json	Output as JSON
--registry	Registry URL to download from
--cache-dir	Cache directory (default: ~/.cache/bz)

bz cache stats

Show statistics about the local module cache.

bz cache stats
bz cache stats --json
bz cache stats --cache-dir=/path/to/cache

Flag	Description
--json	Output as JSON
--cache-dir	Cache directory (default: ~/.cache/bz)

Example output:

Cache directory: /home/user/.cache/bz
Total modules:   15
Total versions:  42
Total size:      12.5 MB
Last updated:    2024-01-15 10:30:00

bz cache verify

Verify that the local cache contains all dependencies required for offline use.

bz cache verify
bz cache verify --json
bz cache verify --cache-dir=/path/to/cache

Flag	Description
--json	Output as JSON
--cache-dir	Cache directory (default: ~/.cache/bz)

Example output:

Verifying cache for MODULE.bazel dependencies...

  ✓ rules_go@0.50.1
  ✓ rules_python@0.35.0
  ✗ gazelle@0.38.0 (missing)

Cache is INCOMPLETE. Run 'bz cache download' to fix.

Returns non-zero exit code if cache is incomplete.

bz cache clear

Clear the local module cache.

bz cache clear                   # clear all (with confirmation)
bz cache clear --force           # skip confirmation
bz cache clear rules_go          # clear specific module
bz cache clear --json

Flag	Description
-f, --force	Skip confirmation prompt
--json	Output as JSON
--cache-dir	Cache directory (default: ~/.cache/bz)

---

Utilities

bz doctor

Check Bazel/bzlmod setup and diagnose common issues.

bz doctor
bz doctor --json

Flag	Description
--json	Output as JSON

Checks performed:

• Bazel installation and version
• MODULE.bazel file existence
• .bazelversion file existence
• Bzlmod enabled status (Bazel 7+ has it on by default)
• Registry connectivity

Example output:

Checking Bazel setup...

✓ Bazel installed (7.0.0)
✓ MODULE.bazel found
✓ .bazelversion found (7.0.0)
✓ Bzlmod enabled (default in Bazel 7+)
✓ Registry reachable (bcr.bazel.build)

All checks passed!

bz registry ping

Test registry connectivity.

bz registry ping                       # check default BCR
bz registry ping https://my.registry   # check specific registry
bz registry ping --json

Flag	Description
--json	Output as JSON

bz completion

Generate shell completion scripts.

Bash

# Linux
bz completion bash > /etc/bash_completion.d/bz

# macOS (Homebrew)
bz completion bash > $(brew --prefix)/etc/bash_completion.d/bz

Zsh

# Enable completion if not already
echo "autoload -U compinit; compinit" >> ~/.zshrc

# Add completion
bz completion zsh > "${fpath[1]}/_bz"

Fish

bz completion fish > ~/.config/fish/completions/bz.fish

PowerShell

# Load for current session
bz completion powershell | Out-String | Invoke-Expression

# Load for every session
bz completion powershell >> $PROFILE

bz version

Print version information.

bz version
bz version --json

Flag	Description
--json	Output as JSON

JSON output:

{
  "version": "0.5.0",
  "commit": "abc1234",
  "date": "2024-01-15T10:30:00Z"
}

---

Exit Codes

Code	Description
0	Success
1	General error (command failed, invalid arguments, etc.)

Commands that perform checks (audit, cache verify, mod licenses --check) return non-zero exit codes when issues are found, making them suitable for CI/CD pipelines.

---

Environment Variables

Variable	Description
BZ_OFFLINE	Enable offline mode (1, true, yes)
BZ_PREFER_OFFLINE	Enable prefer-offline mode
BZ_REGISTRY	Default registry URL
BZ_CACHE_DIR	Cache directory path
BZ_DISABLE_COMMANDS	Disable specific commands (comma-separated)

See Configuration for full configuration options.