Updating AgentKit and kits

The ak CLI and installed kits have separate release lifecycles. Updating the CLI does not replace kit content, and refreshing a kit does not replace the CLI. Check and update each layer deliberately.

Choose a channel

AgentKit publishes stable and beta release channels:

• Choose stable for the regular release line.
• Choose beta when you intend to test prerelease behavior and can review compatibility changes.

Kit commands default to stable; beta requires an explicit opt-in. The CLI self-updater can inherit a saved channel, so pass --channel stable or --channel beta when the choice matters. Keep the CLI and kits on the same intended channel.

The examples below use stable. Replace it with beta as a complete decision, not as a one-off troubleshooting step.

Use the unified updater when appropriate

In an interactive terminal, bare ak update walks through the signed CLI update, global kits, then project kits. Every step defaults to No:

ak update
ak update --yes

--yes accepts the offered steps, but the signed CLI update or minimum-version check remains a hard gate before any kit mutation. Use the scoped commands below when you want to update only one layer. A CLI hard-gate failure, partial kit failure, or interruption after mutation exits 1; an invalid target or scope exits 2.

Review the CLI release

Read the verified changelog, check availability, or fully verify an update without replacing the binary:

ak self-update --changelog --channel stable
ak self-update --check --channel stable
ak self-update --dry-run --channel stable

--changelog is a read-only mode and cannot be combined with update flags. --dry-run downloads and verifies the required artifact in temporary staging, then leaves the installed binary unchanged.

Update the CLI

Apply after the check succeeds:

ak self-update --channel stable --yes
ak --version

The updater verifies release metadata and artifact bytes before replacement. If replacement fails, it restores the previous binary as part of the transaction. There is no user-facing ak backups restore step for a CLI binary update.

Package-manager installs

If the running ak executable belongs to Homebrew or Scoop, ak self-update does not replace it. Run the manager-native command it reports:

brew upgrade ak
scoop update ak

Detection is based on the resolved running executable and the package manager's receipt, not merely on whether the manager is installed somewhere on the machine.

Preview a project kit update

ak update previews by default unless you confirm with --yes. Pin the project, kit, and channel so the plan is unambiguous:

ak update . --kits engineer --channel stable --show-diff
ak update . --kits engineer --channel stable --show-diff --dry-run

The preview does not write files or create a snapshot. It classifies incoming files and shows which user-modified files would be skipped. Without --yes, an implicit scripted preview exits 3; explicit --dry-run performs the same non-mutating preview and exits 0, which is more convenient in CI. Apply the reviewed plan with:

ak update . --kits engineer --channel stable --yes

An applied project update creates a pre-update snapshot before mutation. By default, user-modified files are preserved. Use --force only after reviewing the exact diff and deciding that the snapshot is sufficient recovery; it is not a routine refresh flag.

Preview global kit updates

Global update discovers AgentKit-owned user-scope installs. Preview all of them, or filter by kit and runtime:

ak update --global --channel stable
ak update --global --kits engineer --target codex --channel stable

Apply only after the preview identifies the expected installs:

ak update --global --kits engineer --target codex --channel stable --yes

Global update is preserve-only for user-modified files. A runtime you selected but have not installed globally is reported as skipped rather than created. The same implicit-preview exit 3 and explicit-dry-run exit 0 distinction applies at global scope.

If global Claude Code discovery reaches a Claude home that is not marked as AgentKit-owned, the update refuses the foreign-home takeover before any emitter or ownership mutation. The command may still print a snapshot ID because it takes recovery material before this check; that ID does not mean a partial write occurred. Confirm that the discovered home is the intended global install, then run ak kit init <kit> --global to re-establish ownership before refreshing. Do not restore the snapshot solely because this refusal printed it.

Refresh a specific install route

Use ak kit refresh when you need to preserve an existing target, scope, or Claude Code delivery route exactly:

ak kit refresh engineer --target codex --channel stable --yes
ak kit refresh engineer --global --switch-to-plugin --channel stable --yes

Refresh creates a recovery snapshot, rewrites current AgentKit output, removes stale generated and owned paths only while ownership evidence still matches, and preserves the previous selected-skill subset. Modified, unsafe, linked, and shared paths remain in place. Review the confirmation preview; avoid --no-backup.

Verify the update

After updating:

1. Run ak --version and confirm the channel/version you intended.
2. Review the update summary for skipped or preserved files.
3. Reopen each affected runtime.
4. Invoke one important installed skill in each updated target.

If the kit requires a newer CLI, update ak on the same channel first, then repeat the kit preview.

If the expected files did not change

Work through the route before forcing another write:

1. Confirm the layer: ak self-update changes only the CLI binary, ak update handles AgentKit-owned project content, and ak kit refresh re-emits one installed runtime route.
2. Compare both the CLI version and the resolved Kit version/channel with the versions you expected.
3. Match the original target, project or global scope, and Claude Code native or plugin delivery mode. A different route writes to a different destination.
4. Check whether the file belongs to the previously selected Skill subset.
5. Review the preview and ownership evidence. A user-modified, unknown, linked, or shared path may be preserved intentionally even when the operation succeeds. A refusing foreign-home takeover error instead stops before mutation; follow its exact ak kit init <kit> --global recovery command.

See How installation and refresh work for the ownership classes, reconciliation rules, and worked before/after model. Do not delete an entire runtime directory to make a refresh appear successful.

Recover a kit update

Keep the snapshot ID and recovery path printed by the operation. Inspect a snapshot before restoring it:

ak backups list
ak backups show <id>
ak backups verify <id>
ak recover <id> --dry-run

ak recover is an exact alias for ak backups restore. Restore is replace-only: it overwrites captured files, removes only exact absent paths or explicitly approved AgentKit plugin directories, and normally leaves unrelated files created after the snapshot in place.

If ak backups show <id> lists project bundle roots, repeat every exact root in the recovery command:

ak recover <id> --allow-root /absolute/project --dry-run
ak recover <id> --allow-root /absolute/project

When more than one root is listed, repeat --allow-root with every exact path in both commands.

If the operation says the project snapshot is outside ak backups restore, use the printed snapshot-files directory and copy back only the affected files. Otherwise, apply the reviewed restore plan with ak recover <id> and confirm the prompt. For a project bundle, retain every reviewed --allow-root flag in that apply command.

Restore is not transactional across multiple files; an interruption can leave an intermediate state. Preserve unrelated work and take a new snapshot before rolling backward when practical. Do not recover --latest blindly, delete an entire runtime directory, or rerun the failed update with --force before you understand the current state. Declining restore exits 3, a held backup lock exits 4, an invalid or missing snapshot exits 5, and other failures exit 1.

See also

• Installing kits