Documentation

Guide

Update and migrate

Cumaru has two independent versions. This guide checks both, then refreshes the binary, the project, or the config shape, in that order.

1. Check both versions

IdentityExampleChanged by
CLI build0.15.3cumaru upgrade or Homebrew
Project configconfig.version: 9cumaru migrate only
cumaru upgrade --check
cumaru version

2. Upgrade the binary

If --check reports behind, run cumaru upgrade. It replaces only the global binary and never touches a project. Bare upgrade installs the latest tag even if your build is newer, so always check first.

With Homebrew, upgrade through brew; bare cumaru upgrade is blocked:

brew upgrade rntgspr/tap/cumaru

3. Refresh the project

cumaru update refreshes framework-owned files from main HEAD within the same config version. It previews by default:

cumaru update

Review the plan, commit your work, then publish it:

cumaru update --apply
  • Your tag bodies stay byte for byte. Use --prose or --skip-prose to choose how Markdown prose refreshes.
  • Pending Git changes block --apply. Outside Git, update warns and has no recovery point.
  • cumaru update config prints a reconciliation candidate for config.yaml and writes nothing.

4. Refresh agent files

Adapter artifacts are separate from the tree. Name the agent explicitly:

cumaru update agent claude --skills

Add --apply to publish. To add an opt-in skill, use cumaru update skills <agent> --with <skill> --apply. --clear removes an adapter's owned files at once, without preview.

5. Migrate across a config version

When cumaru version or doctor reports an older config version, update refuses. Print the migration instructions instead:

cumaru migrate

The command writes nothing. Your agent follows the printed steps; each step says how to detect whether it applies, so re-running is safe. There is no rollback: commit or stash first.

Check the result

cumaru doctor

Sources: upgrade, update, migrate, agent adapters. Command details: CLI reference.