#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.

#Machine output

--json is owned by strictcli, not by rlsbl: it is recognized anywhere in the argument list, on every command, and no rlsbl command declares its own. In machine mode stdout carries exactly one document -- the envelope -- and the command's data is its payload member:

{
  "interface_version": 2,
  "app": "rlsbl",
  "app_version": "0.116.0",
  "command": "status",
  "exit_code": 0,
  "payload": {"name": "rlsbl", "version": "0.116.0", "...": "..."},
  "dry_run": false,
  "writes": null,
  "preview": [],
  "preview_error": null,
  "diagnostics": []
}

A consumer reads .payload and nothing else changes about the data it finds there. writes names the write set of an update command and is null on every rlsbl command, none of which is one. Human output is suppressed in machine mode, so a parser never has to strip anything, and --quiet cannot reach the envelope. The commands that produce a payload are status, unreleased, check-name, check, monorepo graph and monorepo impact; each one declares its payload's JSON Schema, which rlsbl --dump-schema publishes verbatim.

#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       # the envelope, with the status data in `payload`
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 run --no-allow-dirty --watch --approve-consequential` or investigate

The whole invocation is printed, not the group name: rlsbl release alone is a command group and prints help, and release run declares --allow-dirty and --watch as required booleans with no defaults.

#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 the project owns. 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   # the envelope, with the coverage report in `payload`

#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, 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 showing the detection status of every supported release target 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.