On this page
Manage a monorepo workspace: init, add/remove projects, sync CI router, release coordination, rename releasables, and dependency graph analysis.
#rlsbl monorepo
Manage monorepo workspaces with multiple independently-versioned projects. Initialize workspaces, add or remove projects, sync CI workflows, check name availability, and analyze dependency graphs. Supports all 18 release targets in a single workspace.toml. Provides 19 monorepo subcommands: init, add, remove, list, sync, status, check-names, outdated, snapshot, snapshot-check, mirror, graph, impact, extract, absorb, extract-releasable, cleanup, migrate-releasable, rename-releasable. Plus 1 subgroup: release.
#monorepo init
Create a new monorepo workspace by generating the .rlsbl-monorepo directory and an empty workspace.toml configuration file at the current directory. This must be run at the repository root before adding individual projects with the add subcommand. Each workspace tracks multiple independently-versioned projects that share a single git repository.
Effect: mutating
Dry run: not supported — it bootstraps the workspace every other command reads, and there is no workspace to preview against until it exists
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--auto-commit | bool | True | Automatically commit the generated workspace.toml configuration file to git |
#monorepo add
Register a project directory in the monorepo workspace.toml configuration. The path argument specifies the project's location relative to the repo root. Supports 6 optional settings: display name, target registry, glob patterns for change detection, subtree remote URL, inter-project dependencies, and a library flag to mark shared code packages.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--name | str | Display name for the project in workspace.toml (defaults to directory name) | |||
--target | str | Registry this project publishes to (e.g. npm, pypi, go) | |||
--watch | str | Comma-separated glob patterns for change detection in CI workflows | |||
--subtree-remote | str | Git remote URL for split-publishing this project as a standalone repo | |||
--depends-on | str | Comma-separated names of workspace projects this project depends on | |||
--library | str | Mark as a shared library consumed by other workspace projects (true/false) | |||
--dev-only | str | Mark as a dev-only leaf node excluded from the dependency boundary guardrail (true/false) | |||
--releasable | str | Releasable group this project belongs to (name of a [[releasables]] entry, or 'false' to opt out of versioning) | |||
--registry-name | str | Package registry identity for this project (used verbatim for name checks; overrides prefix/suffix) | |||
--auto-commit | bool | True | Auto-commit workspace.toml and trigger scaffold/sync commits |
#Arguments
| Name | Required | Description |
|---|---|---|
path | yes | Relative path from the repo root to the project directory to register |
#monorepo remove
Unregister a project from the monorepo workspace.toml by its path. This removes the project entry from the workspace configuration file but does not delete any files, directories, or git history on disk. The project's code remains intact and can be re-added later with the add subcommand if needed.
Effect: mutating
Dry run: not supported — the whole edit is deleting the one workspace.toml entry you just named, and a preview of it would restate the path back to you
#Arguments
| Name | Required | Description |
|---|---|---|
path | yes | Relative path from the repo root of the project to unregister from workspace.toml |
#monorepo list
Display all projects registered in the monorepo workspace.toml file. For each project, shows the project name, relative path from the repo root, target registry for publishing, and any configured options such as watch patterns, subtree remotes, inter-project dependencies, and whether the project is marked as a library.
Effect: read_only
#monorepo sync
Inline every project's CI jobs into a single generated ci-router.yml (and publish jobs into publish.yml) in the shared .github/workflows directory at the repository root. Jobs are inlined rather than routed via reusable-workflow calls because GitHub rejects workflows that reference 20 or more reusable workflows. Stale per-project workflow copies at the root are removed via saferm.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--auto-commit | bool | True | Auto-commit merged workflow files in .github/workflows/ |
#monorepo status
Show the current version, last release tag, and changelog coverage for every project in the monorepo workspace. Coverage is the real JSONL figure -- the commits since the project's last tag, scoped to the project and minus the exempt ones, rendered covered/tracked with an (N exempted) suffix, or 'no changelog' when the project has no changes directory. Provides a quick overview of which projects have pending changes and are ready for their next release.
Effect: read_only
#monorepo check-names
Check package name availability on a target registry for all projects in the monorepo workspace. Queries the registry API for each project name and reports whether it is available or already taken. Supports optional prefix and suffix arguments to test naming conventions like scoped packages, with a configurable delay between registry queries to avoid rate limiting.
Effect: read_only
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--target | str | Registry to query for name availability across all workspace projects (npm, pypi, go, or github) | |||
--prefix | str | String to prepend to each project name before checking availability | |||
--suffix | str | String to append to each project name before checking availability | |||
--delay | str | 200 | Milliseconds to wait between consecutive registry API queries (default: 200) |
#monorepo outdated
Scan all projects in the monorepo workspace for intra-workspace dependencies that reference older versions than what is currently available in the workspace. Lists each outdated dependency with the referenced version and the latest available version, helping identify which downstream projects need a version bump after upstream releases.
Effect: read_only
#monorepo snapshot
Regenerate the committed JSON artifact at .rlsbl-monorepo/snapshot.json summarizing all packages, versions, dependencies, and graph structure, and commit it. Verifying without regenerating is a separate command, rlsbl monorepo snapshot-check. Under --dry-run the artifact is computed but neither written nor committed, and the preview names both steps.
Effect: mutating
#monorepo snapshot-check
Verify that .rlsbl-monorepo/snapshot.json matches the workspace it describes, without regenerating it. Exits 1 when the artifact is stale or missing. This is the read-only half of the former monorepo snapshot --check flag; rlsbl monorepo snapshot is the half that writes.
Effect: read_only
#monorepo mirror
Reconcile a monorepo project's subtree mirror toward its desired state. The mirror is a tool-owned, derived artifact: it observes the remote, then converges it to exactly one scaffold commit atop the current deterministic subtree split, force-pushing (with lease) as the routine write. A tripwire refuses to touch a mirror carrying foreign (hand-authored) commits. Use --dry-run to print a plan (converged, behind, scaffold-missing, contract-violated, or virgin) without writing.
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Arguments
| Name | Required | Description |
|---|---|---|
project | yes | Name of the workspace project to split and push as a standalone mirror repo |
#monorepo graph
Export the monorepo dependency graph in JSON, DOT (Graphviz), or indented text tree format. Supports filtering by a root package (transitive deps) or reverse package (transitive rdeps), with optional depth limiting. Use --output to write to a file instead of stdout.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--format | str | json | Serialization format for the dependency graph: json, dot (Graphviz), or text | ||
--output | str | File path to write the graph output to instead of printing to stdout | |||
--root | str | Filter to show only transitive dependencies reachable from this package | |||
--reverse | str | Filter to show only transitive reverse dependencies of this package | |||
--depth | int | Maximum number of dependency hops to traverse from the root or reverse node |
#monorepo impact
Analyze the impact of changes to a package, file, or git diff range on the monorepo dependency graph. Shows direct and transitive dependents, test scope, and release candidates. Supports package names, file paths, and --since for git-based change detection.
Effect: read_only
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--format | str | text | Output serialization format for the impact report: json or text (default: text) | ||
--depth | int | Maximum number of dependency hops to traverse when computing transitive impact | |||
--since | str | Git ref to diff against HEAD (e.g. HEAD~3, v1.0.0) |
#monorepo extract
Extract a package from the monorepo into a new standalone repository. Clones the monorepo, runs git filter-repo to keep only the package's history, migrates changelog entries, creates .rlsbl/ config in the new repo, and removes the project from workspace.toml.
Effect: mutating
#Arguments
| Name | Required | Description |
|---|---|---|
package_name | yes | Name of the package as defined in workspace.toml to extract into a standalone repo |
target_path | yes | Filesystem path where the new standalone repository will be created |
#monorepo absorb
Absorb an external repository as a package in the monorepo. Rewrites the source's history to live under the destination path, fetch-merges it (preserving full history with rewritten paths), imports its version tags under the monorepo tag scheme, and remaps its JSONL changelog hashes to the new commits.
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--name | str | Workspace project name for the absorbed package (default: basename of the destination path) | |||
--registry-name | str | Package registry identity recorded in workspace.toml (used verbatim for name checks) | |||
--releasable | str | Releasable group to assign the absorbed package to |
#Arguments
| Name | Required | Description |
|---|---|---|
source_repo | yes | Filesystem path to the external git repository to absorb |
dest_path | yes | Destination directory (and workspace path) the source repo's history is rewritten under |
#monorepo extract-releasable
Extract all member packages of a releasable into a new repository. If the releasable has one member, creates a single-project repo. If it has multiple members, creates a new monorepo with workspace.toml. Migrates changelog entries for each member and removes all extracted projects from the source workspace.
Effect: mutating
#Arguments
| Name | Required | Description |
|---|---|---|
releasable_name | yes | Name of the releasable group in workspace.toml to extract |
target_path | yes | Filesystem path where the new repository will be created |
#monorepo cleanup
Remove per-package release-state residue from releasable member packages: .rlsbl/changes/, .rlsbl/releases/, .rlsbl/bases/, .rlsbl/lint/, .rlsbl/version, per-package CHANGELOG.md, and .rlsbl/config.json when identical to the releasable-level config. Per-package hooks/ directories are preserved (live feature), and members whose path is the workspace root are exempt. Deletions go through saferm (audit trail, recoverable) and are committed automatically. Requires an explicit-mode workspace ([[releasables]] in workspace.toml). Detect residue first with rlsbl check --name releasable-residue.
Effect: mutating
#monorepo migrate-releasable
Migrate a releasable from per-package release state to the releasable model. Detects current state, consolidates per-package changelogs and versions into the releasable directory, creates a releasable-format migration tag, and removes orphaned per-package .rlsbl/changes/ and .rlsbl/releases/ directories. Requires the workspace to be in explicit mode (with [[releasables]] in workspace.toml).
Effect: mutating
#Arguments
| Name | Required | Description |
|---|---|---|
releasable_name | yes | Name of the releasable group in workspace.toml to migrate |
#monorepo rename-releasable
Rename a releasable group. Rewrites the [[releasables]] name and every member's releasable field in workspace.toml (preserving comments), moves the state directory, drops the stale changelog validation cache, re-runs monorepo sync, and commits it all as one commit. When tag_format contains {name}, a boundary alias tag for the current version is created at the old tag's commit and pushed; historical releases stay under the old prefix. Idempotent: re-running heals a crash between the commit and the tag push.
Effect: mutating
#Arguments
| Name | Required | Description |
|---|---|---|
old_name | yes | Current name of the releasable group in workspace.toml |
new_name | yes | New name for the releasable group in workspace.toml and state directories |