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
| Identity | Example | Changed by |
|---|---|---|
| CLI build | 0.15.3 | cumaru upgrade or Homebrew |
| Project config | config.version: 9 | cumaru 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
--proseor--skip-proseto choose how Markdown prose refreshes. - Pending Git changes block
--apply. Outside Git, update warns and has no recovery point. cumaru update configprints a reconciliation candidate forconfig.yamland 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.