Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Start here

monochange is easiest to learn with one safe local walkthrough.

In about 10 minutes you will:

  • install the CLI
  • generate a starter monochange.toml with mc init
  • validate the workspace
  • discover package ids
  • create one change file
  • preview a release plan with --dry-run

This first run is safe: nothing is published.

1. Install the CLI

The fastest path is the prebuilt npm package:

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

If you prefer a Rust-native install, use:

cargo install monochange
monochange --help
mc --help

2. Generate a starter config

Run mc init at the repository root:

mc init

mc init scans the repository, detects packages, and writes an annotated starter monochange.toml.

Start with the generated file instead of hand-authoring your first config.

3. Validate the workspace

mc step:validate

This checks monochange.toml and your .changeset/*.md files together.

4. Discover package ids

mc discover --format json

Look for the package ids you will use in changesets and CLI commands.

If you do not know which id to target later, rerun discovery and copy one directly from the output.

5. Create one change file

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

Most first changes should target a package id.

Use group ids only when the change is intentionally owned by the whole group.

A typical generated file looks like this:

---
<id>: patch
---

#### describe the change

If the same package changed for a more specific reason, you can add more context right away:

mc change \
  --package <id> \
  --bump minor \
  --reason "add release preview improvements" \
  --details "Adds file diff previews during dry runs."

6. Preview the release plan safely

mc release --dry-run

By default this now renders a human-friendly markdown preview in the terminal. Use --format json when you want structured output for tooling, --format text when you explicitly want the older plain-text rendering, or mc versions when you only need the planned package and group versions. mc versions is read-only, so it will not update release files.

When you want to see the exact file patch without mutating the workspace, add --diff:

mc release --dry-run --diff

When you want to inspect changeset provenance before releasing, add a diagnostics pass:

mc step:diagnose-changesets --format json

Stop here on your first run. This previews the release plan without publishing anything.

Package ids first, groups later

A good first-time mental model is:

  1. monochange discovers packages.
  2. You author explicit changes against package ids.
  3. monochange propagates dependent bumps for you.
  4. Groups synchronize packages that intentionally share release identity.

That is why most beginner flows should start with package ids, not groups.

If you need a silent safety check, run mc release --quiet. Quiet mode suppresses stdout/stderr and keeps release-oriented commands in dry-run behavior.

If you hit a problem

  • mc init says a config already exists: keep the existing monochange.toml and continue with mc step:validate, or pass --force to regenerate.
  • mc step:validate reports problems: fix the reported config or changeset issue, then rerun mc step:validate.
  • mc change rejects your target: rerun mc discover --format json and copy a valid package id.
  • You are not sure what to do next: continue with Your first release plan.

Next steps