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, scope, or source exits 2.

On Windows, that CLI gate applies the replacement in place under an exclusive update lock, validates the running binary preimage, then re-executes the original ak update command so Kit refresh continues on the first invocation. Standalone ak self-update still uses the staged detached helper. Paired Desktop apply stages the matching CLI and Desktop artifacts, then a trusted helper commits the swap after the parent process releases the executables.

The wizard projects one --target selection onto each step. For example, pi remains eligible for the project step but is omitted from the global Kit step; if no selected target applies globally, the wizard skips that step and continues. An explicit target that does not apply to the selected scope and source is rejected before discovery or mutation.

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

By default, an applied project update snapshots only the exact files it writes or prunes — a restorable bundle, whose result includes the restore command. --force, --backup, or backups.enabled: true in ~/.agentkit/config.yaml captures the whole project instead; --no-backup skips the snapshot entirely, including the one --force takes. 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.

Background auto-update (opt-in)

ak update --schedule daily|weekly enables a detached background update that starts on the first ordinary ak command after the interval, refreshing the CLI and global kits plus any project opted in with --project <dir> (registered via ak projects add) whose git tree is clean and has no live agent session:

ak update --schedule daily --project .
ak update --status --json
ak update --schedule off

The settings flags (--schedule, --project, --no-project, --status, --ack) only change auto_update: in ~/.agentkit/config.yaml or read state; they never apply an update themselves and cannot combine with an update flag or a project-dir argument. Background updates never start with AK_NO_AUTO_UPDATE=1 or CI set, for --json invocations, or for lifecycle/interactive commands such as update, init, or kit. A Kit hook (session-heartbeat.cjs) marks a project as having a live session so the updater skips it; an unacknowledged result prints once at the next SessionStart and can be acknowledged with ak update --status --ack --json. See the ak update reference and the auto_update ak doctor check for details.

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
ak update --global --kits engineer --local --kits-dir ./kits --target grok

Apply only after the preview identifies the expected installs:

ak update --global --kits engineer --target codex --channel stable --yes
ak update --global --kits engineer --local --kits-dir ./kits --target grok --yes

Global update is preserve-only for user-modified files. Target validity depends on both scope and source: remote project updates accept exactly one of claude-code, codex, cursor, dsh, grok, omp, or pi; remote global updates accept claude-code, codex, cursor, dsh, grok, or omp; local global updates accept the same set. Use --target or its --runtime alias, but pass only one flag name. An explicit target that does not apply to the selected scope and source is rejected before discovery or mutation.

A selected runtime that is not installed globally is reported as skipped rather than created. In an unfiltered remote --global run, an existing local-only install remains visible as a skipped result with reason source_inapplicable; it is not refreshed from another source implicitly. Follow its next guidance and run ak update --global --local --kits-dir <dir>. 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.

When you filter follow-up diagnostics, ak doctor --adapter accepts only claude-code, codex, and cursor, which have dedicated doctor suites. Any other adapter value is invalid and exits 2 instead of returning an empty successful check set.

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