CLI Commands

The brel binary exposes six subcommands. There are no global flags besides --version and --help; every subcommand accepts its own --config.

brel <command> [options]

All commands resolve their configuration the same way: an explicit --config <path> wins, otherwise brel looks for brel.toml, then .brel.toml in the current directory. See Configuration for the full schema.

Errors are printed to stderr as Error: <message> and exit with code 1.

brel init

Initialize release workflow scaffolding. Generates (or updates) the managed CI workflow file for your configured forge — GitHub Actions, GitLab CI, or Forgejo Actions — and persists your choices into the config file.

By default init runs interactively, prompting for the forge, main branch, changelog on/off, changelog provider, tag-on-merge, and tag template.

Flag	Description
--config <path>	Path to a config file. Defaults to brel.toml, then .brel.toml.
--yes	Run non-interactively and auto-confirm overwrite prompts.
--dry-run	Show a diff of what would change without writing files.

Caution

brel init is not supported for provider = "gitea". See the Gitea guide.

# Interactive setup
brel init

# Non-interactive, using the existing config
brel init --yes

# Preview changes without writing anything
brel init --dry-run

brel changelog

Generate the configured changelog for the next release. Computes the next version using the versioning rules, then runs the configured changelog provider (git-cliff or changelogen).

If changelog generation is disabled, or no releasable commits exist, the command exits successfully without changing files.

Flag	Description
--config <path>	Path to a config file.

Requires the provider runtime to be installed: git-cliff for git-cliff, npx for changelogen. See Changelog Generation.

brel release-pr

Create or update a release PR. Computes the next version, updates the files configured in version_updates, commits as brel[bot], pushes the release branch (--force-with-lease to origin), and creates or updates the managed release PR/MR.

Flag	Description
--config <path>	Path to a config file.

Requires forge credentials — see Environment Variables. If no releasable commits are found, the command exits successfully with no changes.

brel tag

Create and push a release tag.

Flag	Description
--config <path>	Path to a config file.
--tag <tag>	Release tag to create. When omitted, provider merge event data is used (event mode).
--target <rev>	Git revision to tag. Defaults to HEAD in manual mode, or the PR merge commit in event mode.

Two modes:

• Event mode (no --tag): reads the forge’s merge event payload (e.g. GITHUB_EVENT_PATH) to detect a merged managed release PR and tags its merge commit. This is what the generated CI workflow uses. Event mode supports the github, gitlab, and forgejo providers.
• Manual mode (--tag provided): creates the given tag directly, at --target or HEAD. Works even when tagging-on-merge is disabled in config.

brel tag --tag v1.2.3 --target HEAD

The tag is validated against release_pr.tagging.tag_template before being created and pushed to refs/tags/<tag> on origin. See Tagging on Merge.

brel next-version

Compute the next releasable version and print it as plain SemVer (for example 1.2.3).

Flag	Description
--config <path>	Path to a config file.

When no releasable commits exist, it prints nothing and exits successfully — convenient for scripting:

next="$(brel next-version)"
if [ -n "$next" ]; then
  echo "next release: $next"
fi

brel validate

Validate a config file. Prints Config file `<path>` is valid. on success, and emits warning: lines for unknown or ignored keys. Errors (exit 1) if no config file is found or the config is invalid.

Flag	Description
--config <path>	Path to a config file.

brel validate
brel validate --config ./configs/release.toml