Compare

Which command does what?

Command	Updates	Does not	When
ak self-update	The ak CLI (and Desktop if you opt in)	Does not refresh skills/hooks in projects	You only want a newer ak CLI
ak update	Walks through: ak CLI → machine kits → project kits	Skips any step you decline	After a release: refresh guided step by step
ak update --global	Only kits installed machine-wide (or filter with --target)	Does not touch project folders	Refresh machine kits without opening a repo
ak update [project-dir]	Only AgentKit-installed files in that project	Does not refresh machine-wide kits	Update kits inside one repo
ak update --kits <name>	Only that kit name (in the project, or with --global)	Does not touch other kits	Only engineer / marketing / …
ak kit refresh <kit>	Force re-apply one installed kit; drop leftover generated files	Not the multi-step ak update walkthrough; not a CLI upgrade	One kit is out of date or needs a hard refresh

1 · CLI

ak CLI only: ak self-update

Use when you only want a newer ak CLI (or staged Desktop). Does not refresh skills/hooks in projects.

shell

# Check only — no install
ak self-update --check

# Apply signed CLI update
ak self-update --yes

# Beta channel shorthand
ak self-update --beta --yes

# Require matching CLI + Desktop artifacts for this platform
ak self-update --include-desktop --yes

# Opt in / out Desktop auto-update (writes config.yaml updates.*)
ak self-update --enable-auto-update
ak self-update --disable-auto-update

2 · Kits

Refresh Kit content: ak update

Only updates files AgentKit installed (not files you created yourself). Without --yes you usually get a preview; add --yes to apply for real.

Update step by step (asks each time)

Run bare ak update in an interactive terminal. It walks you through: upgrade the ak CLI → kits on this machine → kits in the current project. You answer Yes/No each step. Add --yes to accept every step.

ak update → ask each step
ak update --yes → accept every step

Only one place / one kit (skip the long wizard)

Add flags to say “only this scope” so you skip the full three-step wizard. --global = machine-wide kits; a project path = one repo; --kits = only that kit name.

ak update --global --yes → machine kits only
ak update ./myproj --yes → one project only
ak update --kits engineer --yes → engineer kit only

Three steps when you run bare ak update (interactive terminal)

1

1. The ak CLI

Asks whether to upgrade the ak CLI. Default is No; answer Yes or use --yes to accept the whole wizard.
2

2. Kits on this machine (global)

Refreshes kits installed for your user/machine. Files you edited by hand are usually kept.
3

3. Kits in the project

Refreshes kits in the current project folder. Untouched AgentKit files update; files you changed are skipped unless you add --force.

Global kits only (machine-wide)

shell

# Preview user/global kit refreshes
ak update --global

# Apply
ak update --global --yes

# One kit, global
ak update -g --kits engineer --yes

# One or more runtimes only
ak update --global --target codex --yes
ak update --global --target claude-code,codex --yes

On the machine (global): files you edited by hand are usually kept — --force does not overwrite them the way it can in a project. Claude Code user-plugin-only installs are reported, not silently refreshed; use ak kit refresh … --global --switch-to-plugin when you need that path.

Project kits only

shell

# Preview current directory project
ak update ./myproj
# or from inside the project:
ak update

# Preview one kit
ak update --kits engineer

# Apply (required for scripted / non-TTY)
ak update --kits engineer --yes

# Overwrite user-modified AK-owned files too
ak update --kits engineer --force --yes

# Show unified diffs in preview
ak update --show-diff

# Scripted envelope
ak update --kits engineer --yes --json --no-interactive

Channel / beta

shell

# shorthand --channel beta
ak update --beta --yes
ak update --channel stable --yes
# --beta conflicts with --channel stable

3 · One kit

One kit (force re-emit): ak kit refresh

Unlike ak update --kits alone: refresh re-emits with force and unloads generated files that left the kit source.

shell

# Project-native Claude Code (remote default)
ak kit refresh engineer --yes

# Project plugin delivery
ak kit refresh engineer --switch-to-plugin --yes

# Global paid install
ak kit refresh engineer --global --yes

# Specific runtime
ak kit refresh engineer --target codex --yes

# Local kit source (dev)
ak kit refresh engineer --local --kits-dir ./kits --yes

Use when audit reports plugin drift, after kit export changes, or when you need to rewrite one kit’s output. Snapshot by default (unless --no-backup).

Practice

Quick pick

Only want a newer ak CLI

ak self-update --check ak self-update --yes

After release, refresh “everything” (CLI + kits)

ak update --yes (accept every step)

Only global kits on this machine

ak update --global --yes

Does not upgrade the ak CLI — use ak self-update if you need that.

Only this repo / one kit

ak update --kits engineer --yes or ak kit refresh engineer --yes

Update AgentKit CLI & Kits

Which command does what?

ak CLI only: ak self-update

Refresh Kit content: ak update

Update step by step (asks each time)

Only one place / one kit (skip the long wizard)

Three steps when you run bare ak update (interactive terminal)

1. The ak CLI

2. Kits on this machine (global)

3. Kits in the project

Global kits only (machine-wide)

Project kits only

Channel / beta

One kit (force re-emit): ak kit refresh

Quick pick

Related