How to upgrade an installed pack

Use this when: You want to move an installed pack to a newer version — whether a whole pack, a single primitive, or resolving companion files left by a previous upgrade. Prerequisites: A pack already installed from the catalogue and the agentbundle CLI on your PATH; see Prerequisites. Result: The pack upgraded to the newer version with any local edits preserved as .upstream.<ext> companion files for selective merging.

Move an installed pack to a newer version, with the conflict handling you expect when your local edits and the upstream pack have both moved on.

Prerequisites

• A pack already installed from this catalogue via one of the three routes (Claude Code plugin marketplace, APM, or the agentbundle CLI).
• For the catalogue-native flow: the agentbundle CLI on your PATH.
• For catalogue-level safety on APM and Claude-plugin installs: a one-time agentbundle init-state run after the original install.

Pick the right granularity

Three granularities are available, in order of increasing specificity.

Whole pack (default)

Pick the verb that matches how you originally installed.

• APM: apm update <pack>.

• Claude Code plugins: /plugin update <pack>@<catalogue>.

• agentbundle CLI:

  agentbundle upgrade --pack <name> <catalogue>

upgrade takes no version — the target is whatever the catalogue you point at declares. To move to a specific past version, point <catalogue> at that git ref.

The first two use the host tool’s native verbs and follow that tool’s conflict-resolution rules, not the catalogue’s. The agentbundle upgrade verb is the only route that drops *.upstream.<ext> companions next to any Tier-2 file whose content has diverged since install — letting you walk the merges later via the adapt-to-project skill (see One file at a time below). Before it writes, it tells you how many of your edited files it will preserve as companions.

<catalogue> is the same URI you installed from, e.g. git+https://github.com/<owner>/<catalogue> or a local checkout path.

Tip

Check first. agentbundle list-installed shows every installed pack with its version and whether an upgrade is available — run it before upgrading to see what’s outstanding (see the CLI reference).

Note

Multiple adapters. If a pack is installed for more than one adapter at the scope, upgrade upgrades one adapter per run and asks you to --adapter which; the message lists each adapter with its version. Re-running against the version you already have is reported as re-applied … (already current), not a version change.

Caution

Pitfall — install --pack is not the upgrade verb. agentbundle install --pack refuses an in-place re-install. Use upgrade --pack to change an installed pack’s version.

One primitive at a time

Add a primitive filter to the same upgrade verb:

agentbundle upgrade --pack <name> --skill <skill-name> <catalogue>

--agent, --hook, --seed <path>, and --command work the same way. Only the named primitive moves; the rest of the pack stays at the previously-installed version. The CLI records the resulting mixed-version state in .agentbundle-state.toml; the next whole-pack upgrade flags it.

One file at a time

Re-invoke the adapt-to-project skill. It walks any *.upstream.<ext> companions still on disk one by one, with per-file accept / edit / skip / decline. This is the merge UI for the companions a previous agentbundle upgrade (or first-install collision) left behind.

Downgrades

Not supported in v0.1. To roll back: agentbundle uninstall --pack <pack> and reinstall at the prior version. Tier-2 (your edited copies) and Tier-3 (files outside the pack’s projected paths) survive the uninstall by design — only the upstream-managed Tier-1 files are removed.

Related

• How to adapt a freshly-installed pack — the skill that walks *.upstream.<ext> companions.