Introduction

monochange is a cross-ecosystem release planner for monorepos.

It is easiest to learn with one safe local walkthrough before you touch provider publishing, release PRs, diagnostics, or MCP setup.

Who this guide is for

• maintainers of monorepos that span more than one package ecosystem
• teams replacing ad hoc release scripts with explicit change files
• people who want a predictable release plan before adding automation

Start with one safe walkthrough

Install the prebuilt CLI from npm:

npm install -g @monochange/cli
monochange --help
mc --help

Then run the core beginner flow:

Generate a starter config from the packages monochange detects:

mc init

mc init writes an annotated, minimal monochange.toml without default [cli.*] workflow aliases. The binary exposes immutable mc step:* commands for every built-in step when you need a direct, config-free entry point; add [cli.*] tables only for repository-specific named workflows.

For automated CI setup, include the --provider flag:

mc init --provider github

This configures the [source] section, generates CLI commands for commit-release and release-pr, and creates GitHub Actions workflows.

Validate the workspace:

mc step:validate

Discover the package ids you will use in commands and changesets:

mc discover --format json

Create one change file for a package id:

mc change --package <id> --bump patch --reason "describe the change"

Most changes should target a package id. Use group ids only when the change is intentionally owned by the whole group.

When a package is only changing because another dependency or version group moved first, author that context explicitly instead of relying on anonymous propagation:

mc change --package <dependent-id> --bump none --caused-by <upstream-id> --reason "dependency-only follow-up"

Preview the release plan safely:

mc release --dry-run --format json

Add --diff when you want unified file previews for version and changelog updates without mutating the workspace:

mc release --dry-run --diff

This first run is safe: nothing is published. Stop here until you are ready to prepare release files locally.

When you are ready to prepare the release locally, run mc release.

For human-readable local output, mc release --dry-run now defaults to terminal-friendly markdown. Use --format json for automation, --format text when you explicitly want the older plain-text rendering, mc versions when you only need planned package and group versions, and --quiet when you want dry-run behavior without stdout/stderr output. mc versions is a dedicated non-mutating summary command and also supports --format markdown and --format json.

This book is maintained with mdt so shared content blocks stay synchronized across pages. See the Configuration reference for how template updates work.

If you want a slower, more guided walkthrough, continue with Start here and Your first release plan.

What to read next

• Start here — install, mc init, validation, discovery, and --dry-run
• Installation — npm, Cargo, optional assistant tooling, and repository development setup
• Your first release plan — generated config first, package ids before groups
• Configuration reference — the full package, group, changelog, and CLI model
• Release planning — changesets, dry runs, diff previews, and planning rules
• Advanced: GitHub automation — provider publishing and release requests
• Advanced: CI, package publishing, and release PR flows — per-provider CI patterns, trusted publishing, and long-running release PR design notes
• Advanced: Assistant setup and MCP — optional AI-assisted workflows
• Reference: Manifest linting with mc check — [lints] rules for Cargo and npm-family manifests

Recent package publishing improvements

Recent monochange improvements made package publishing guidance and diagnostics much more actionable:

• a dedicated trusted-publishing guide now covers npm, crates.io, jsr, and pub.dev
• CI examples now prefer the official registry-maintained workflows for crates.io and pub.dev
• a dedicated multi-package publishing guide now covers monorepo tag, workflow, and package-boundary patterns
• CLI output now gives clearer manual next steps for registries that still require registry-side trusted-publishing enrollment
• built-in publish preflight now validates and reports the expected GitHub repository, workflow, and environment context for manual registries when it can infer them

Command and automation matrix

These are common commands for repositories using monochange. With the current CLI model, workflow names such as discover, change, release, publish, and affected come from optional [cli.*] tables in monochange.toml; binary commands such as check, init, and mcp stay built in, while typed built-in operations such as validation are exposed as immutable mc step:* commands.

mc step:publish-readiness performs non-mutating registry checks before mc publish. For built-in Cargo publishes to crates.io it also verifies current manifest publishability: publish = false blocks publishing, publish = [...] must include crates-io, description must be set, and either license or license-file must be set. Workspace-inherited Cargo metadata is accepted, and already-published versions remain non-blocking in readiness reports. The artifact fingerprints monochange.toml, package manifests, lockfiles, and registry/tooling files, so rerun mc step:publish-readiness after those inputs change. mc publish-plan --readiness <path> validates the artifact for planning and limits rate-limit batches to package ids that are ready in both the artifact and the fresh local readiness check. mc publish publishes directly from prepared release or HEAD release state and does not require the readiness artifact. If readiness shows missing first-time registry packages, run mc step:placeholder-publish --from HEAD --output .monochange/bootstrap-result.json, then rerun readiness before real publishing.

What monochange can do today

• discover Cargo, npm/pnpm/Bun, Deno, Dart, Flutter, Python, and Go packages
• normalize dependency edges across ecosystems
• coordinate shared package groups from monochange.toml
• compute release plans from explicit change input
• expose top-level CLI commands from [cli.<command>] definitions
• run config-defined release commands from .changeset/*.md
• render changelogs through structured release notes and configurable formats
• emit stable release-manifest JSON for downstream automation
• preview or publish provider releases and release requests from typed command steps and shared release data
• inspect durable release records from tags or descendant commits with mc step:release-record
• create post-merge release tags from a merged release commit with mc step:tag-release --from HEAD
• repair a recent source/provider release by retargeting its release tags with mc repair-release
• inspect changeset context and review metadata with mc step:diagnose-changesets for both human and automation workflows
• apply Rust semver evidence when provided
• expose a bundled assistant skill plus a stdio MCP server with mc mcp
• publish the CLI as @monochange/cli and the bundled agent skill as @monochange/skill
• publish end-user documentation through the mdBook in docs/

What the JSON output includes

Discovery output includes:

• normalized package records
• dependency edges
• release groups derived from configured groups
• warnings

Release-plan output includes:

• per-package bump decisions
• synchronized group outcomes
• compatibility evidence
• warnings and unresolved items
• optional fileDiffs previews when you request --diff

Contributing to monochange itself

If you are working on the monochange repository, run the full local validation suite before opening a PR:

lint:all
test:all
build:all
build:book