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 monochange 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

If you prefer a Rust-native install, use:

cargo install monochange
monochange --help

If you use devenv, add monochange via the ifiokjr/nixpkgs overlay:

# flake.nix
inputs.ifiokjr-nixpkgs.url = "github:ifiokjr/nixpkgs";

# devenv.nix
let extra = inputs.ifiokjr-nixpkgs.packages.${pkgs.stdenv.system};
in {
  packages = [ extra.monochange ];
}

Or run directly:

nix run github:ifiokjr/nixpkgs#monochange

2. Generate a starter config

Run monochange init at the repository root:

monochange init

monochange 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

monochange step validate

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

4. Discover package ids

monochange step 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

monochange run 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:

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

6. Preview the release plan safely

monochange run release --dry-run

By default this renders concise text in the terminal. Use --format markdown when you want a raw Markdown artifact, --format json when you want structured output for tooling, or monochange step display-versions when you only need the planned package and group versions. Use monochange versions --dry-run when you want to preview internal dependency constraint updates without modifying manifests.

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

monochange run release --dry-run --diff

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

monochange 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 monochange run release --dry-run --quiet. Quiet mode only suppresses output; --dry-run is what prevents workspace changes.

If you hit a problem

  • monochange init says a config already exists: keep the existing monochange.toml and continue with monochange step validate, or pass --force to regenerate.
  • monochange step validate reports problems: fix the reported config or changeset issue, then rerun monochange step validate.
  • monochange run change rejects your target: rerun monochange step 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