#Utility commands

rlsbl includes several utility commands alongside its core release, changelog, scaffold, and check workflows. These commands handle day-to-day tasks like inspecting project state, preparing for releases, and managing machine-generated files.

#rlsbl commit

Create commits with an Autogenerated: true trailer that signals the commit contains machine-generated content. These commits are automatically exempted from changelog coverage checks during validation and pre-push enforcement, making them the correct way to commit selfdoc output, strictcli schema dumps, and validation cache files.

#Usage

rlsbl commit -m <message> -- <file1> [file2 ...]

#Behavior

• Stages the specified files and commits them with the given message
• Appends an Autogenerated: true trailer to the commit (requires git 2.32+)
• Uses safegit if available, falls back to raw git
• The pre-push hook recognizes the trailer and skips JSONL coverage checks for these commits

#When to use

#When NOT to use

Do not use rlsbl commit for human-authored changes. Those need proper changelog entries. The trailer is a signal that the commit's content was produced by a tool and carries no user-facing meaning.

#rlsbl status

Show the project's current version, git branch, last release tag, working tree cleanliness, and changelog coverage at a glance. This is the primary command for quickly assessing whether a project is ready for release or has pending work.

#Usage

rlsbl status              # plain text output
rlsbl status --json       # structured JSON output
rlsbl status --target go  # target a specific registry

#Output fields

When unreleased commits exist, a warning line appears:

! 3 commits ahead of v0.45.0 -- run `rlsbl release` or investigate

#Monorepo awareness

When run inside a monorepo sub-project, rlsbl status automatically scopes its output to that project by filtering tags to only those matching the project's naming pattern and counting only commits that touch files within the project's directory or watch patterns. This prevents cross-project noise in workspaces with many independently-versioned packages.

#rlsbl unreleased

List commits between the last tag and HEAD with their changelog coverage status. This is the primary tool for preparing a release -- it shows exactly which commits still need JSONL entries.

#Usage

rlsbl unreleased          # plain text
rlsbl unreleased --json   # structured JSON

#Output (unreleased)

Each commit in the unreleased range is listed with full details for preparing a release. The coverage status column indicates whether a corresponding JSONL entry exists, making it easy to identify which commits still need changelog entries:

• Full SHA
• Subject line
• Author
• Date
• Whether it has a corresponding JSONL entry (covered/uncovered)

#Decision table

#rlsbl targets

List all release targets detected in the current project directory, showing which ecosystems (npm, PyPI, Go, Cargo, etc.) are active based on manifest files found. This helps verify that rlsbl will detect the correct targets before scaffolding CI or initializing a release.

#Usage

rlsbl targets

#Output (targets)

A table with 3 columns showing the detection status of all 18 supported release targets in the current project directory. Each row indicates whether the target's manifest file was found and which file stores the version:

#Use case

Before running rlsbl release init or rlsbl scaffold, check which targets rlsbl will detect. If a target is missing, ensure its manifest file exists (e.g., pyproject.toml for pypi, package.json for npm).

#rlsbl discover

Search GitHub for repositories tagged with the rlsbl topic, providing an overview of the rlsbl ecosystem. Use --mine to filter results to only your own repositories, which is useful for auditing which of your projects have rlsbl configured.

#Usage

rlsbl discover          # all rlsbl-tagged repos
rlsbl discover --mine   # only your own repos

#Requirements

• gh CLI installed and authenticated (for --mine and higher rate limits)
• Without authentication: 60 API requests/hour
• With authentication: 5000 API requests/hour

#Output (discover)

A table of rlsbl-tagged repositories on GitHub, sorted by last updated timestamp and paginated up to 1000 results via the GitHub Search API. With authentication, queries can use up to 5000 API requests per hour. Each row shows:

• owner/repo -- full repository name
• description -- repo description (truncated to 40 chars)
• updated -- relative time since last update (e.g., 2d ago)

Results are sorted by last updated, paginated up to 1000 repos.

#rlsbl prs

List all open pull requests for the current repository, showing PR number, title, author, and branch. This provides a quick check for in-flight work before starting a release or making changes that might conflict with pending PRs.

#Usage

rlsbl prs

#Behavior

• Shows PR count and a table of open PRs (number, title, author, branch)
• Requires gh CLI installed and authenticated
• Designed to be safe for hooks -- always exits 0, never crashes the session
• If gh is not installed or not authenticated, prints a message to stderr and exits 0

#Use case

Run before releasing to check for in-flight work that might conflict with or depend on the release. This is especially important in monorepo workflows where multiple contributors may have PRs targeting different sub-projects, and a release could invalidate their base versions.

#rlsbl migrate

Run pending configuration migrations to update .rlsbl/ config files to the latest schema. When rlsbl introduces breaking config format changes between versions, migrations handle the transformation automatically so you do not need to manually rewrite configuration files.

#Usage

rlsbl migrate            # apply pending migrations
rlsbl migrate --dry-run  # preview changes without applying
rlsbl migrate --status   # show which migrations are pending

#Requirements

Migrations are executed by an external tool called migrable, which must be installed separately as a Go binary. It handles schema transformations as versioned migration scripts, applying them in order and tracking which migrations have already run to prevent double-application:

go install github.com/smm-h/migrable/cmd/migrable@latest

#Behavior

• Delegates to the external migrable binary
• Operates on the .rlsbl/ config directory
• Migrations are schema upgrades (e.g., renaming config keys, restructuring JSON)
• Exit code matches migrable's exit code

#When to use

Run rlsbl migrate after upgrading rlsbl to a new version that introduces config format changes, such as renamed JSON keys, restructured objects, or new required fields. If rlsbl check reports schema issues or validation errors against your .rlsbl/config.json, run rlsbl migrate --status to see if a migration is available that can automatically transform the config to the new schema.

#rlsbl record-gif

Record a terminal demo GIF of the project's CLI help output using the vhs terminal recorder from Charm. This produces consistent, reproducible demo recordings suitable for README files and documentation sites, with configurable dimensions and timing.

#Usage

rlsbl record-gif
rlsbl record-gif --width 1400 --height 800 --font-size 28 --duration 15

#Flags

#Requirements

• vhs (charmbracelet/vhs) installed: go install github.com/charmbracelet/vhs@latest

#Behavior

1. Auto-detects the project's binary command name from release targets
2. Generates a temporary VHS tape file that types <binary> --help and records the output
3. Saves the result to assets/demo.gif
4. Cleans up the temporary tape file

#Limitations

• Requires a detectable CLI entry point (package.json scripts, pyproject.toml console_scripts, or go.mod)
• Times out after 120 seconds
• The recorded command is always <binary> --help -- not configurable