Updates

agentkrew update refreshes an existing installation to a newer AgentKrew version — and the whole design exists to answer one question: will I lose my customizations? The answer is no, by construction, not by hope.

How a version change reaches you

Two versions matter:

• Installed version — agentkrewVersion in your project's .agentkrew.json, stamped at init time.
• Available version — the version of the agentkrew CLI you are running.

update compares them. If they match you get:

AgentKrew is already up to date (0.2.1).

(exit code 0). If your installed version is newer than the CLI you ran, it says so and does nothing (also exit 0). So the practical upgrade sequence for a newer release is:

npx @agentkrew/cli@latest update

— run the new CLI against your project.

What an update does

When an update is available, update:

1. Reads .agentkrew.json (runtime, kit or kits, artifact inventory).

2. Resolves the kit sources and re-renders every artifact through your runtime's adapter — the same deterministic rendering as init.

3. Safety net: refuses to proceed if any rendered path is not classified generated (refusing to overwrite user-owned files).

4. Prints the full change plan before writing:

   text

   AgentKrew update
   
   Project root: /path/to/project
   Version: 0.2.1 → 0.3.0
   AGENTKREW.md is user-owned — your edits will be preserved.
   Will refresh 43 files + .agentkrew.json:
     .claude/agents/accessibility-specialist.md
     .claude/agents/api-designer.md
     ...

5. Snapshots every file it is about to write, then writes the refreshed generated files and the updated manifest.

6. Creates AGENTKREW.md if and only if it is absent (create-only; your version is never touched).

7. Runs post-update validation (all expected artifacts present, references intact).

8. If validation fails: restores every snapshotted file and the old manifest byte-for-byte, and exits non-zero. A failed update never leaves a broken installation.

What survives an update

The acceptance scenario the update tests enforce:

install v0.1 → user edits configuration → update to v0.2
→ the user modification is intact, shipped files are refreshed

Exit codes

• 0 — updated, already up to date, or nothing to do.
• 1 — failure: no manifest, unsupported runtime, unresolvable kit, refusal to touch user-owned paths, or failed post-update validation (rolled back).

update writes its change plan and summary to stdout; failures go to stderr, so it is script- and CI-friendly.

Kit sources on npm installs

The npm package does not bundle kit sources (kits are delivered through the license registry), while update re-renders from kit sources on disk. So update resolves each kit in this order:

1. AGENTKREW_KIT_ROOT, when set — an explicit directory is authoritative and never triggers a download:

   bashcopy

   AGENTKREW_KIT_ROOT=/path/to/kits npx @agentkrew/cli@latest update

2. The kits/ directory of a source checkout of AgentKrew.

3. The license registry: with AGENTKREW_LICENSE_KEY exported, missing kits are downloaded and checksum-verified, re-rendered, and the downloaded copy is cleaned up afterwards.

Without a key and without kits on disk, update stops with guidance instead of guessing:

agentkrew update: unknown kit "engineer" (available: none): kit sources are not on disk. Kits are not bundled with the npm package — set AGENTKREW_LICENSE_KEY to download them from the registry, or AGENTKREW_KIT_ROOT to a kits directory.

list --installed and info --installed resolve kits the same way. Either way, your customization is at risk from none of this: the write rules above apply identically.

See also

• customization — where to put changes so every rule in this page works in your favor.
• architecture — why generated files are disposable and reproducible.