ak self-update

Check, verify, stage, or apply signed AgentKit CLI and optional Desktop updates with explicit ownership and recovery limits.

Use ak self-update for the AgentKit binary lifecycle. It does not refresh project or user Kit files; use ak update or ak kit refresh for those layers.

Usage

ak self-update

The command accepts no positional arguments.

Without --yes, the command checks availability and does not download an artifact. It never asks an interactive question, regardless of TTY or stdin. The binary channel resolves in this order: --channel (or --beta), the saved updates.channel, the channel of the running release binary, then stable. Development builds without a saved preference resolve stable. An explicit --channel is saved only when you also pass --enable-auto-update or --disable-auto-update.

AgentKit first detects ownership of the running executable. A verified Homebrew or Scoop install is not replaced in place; the result reports brew upgrade ak or scoop update ak and makes no release request. Uncertain manager ownership fails closed.

Options

Flag	Default	Description
`--beta`	`false`	Shorthand for `--channel beta`; conflicts with an explicit non-beta channel.
`--changelog`	`false`	Print the verified release changelog without checking or applying an update.
`--channel <channel>`	`updates.channel`, running binary channel, then `stable`	Select `dev`, `beta`, or `stable`. Other values exit `2`.
`--check`	`false`	Check signed metadata without downloading artifacts.
`--disable-auto-update`	`false`	Set Desktop auto-update checks and staged apply to disabled.
`--dry-run`	`false`	Download and verify selected artifacts in a temporary directory without replacing the install.
`--enable-auto-update`	`false`	Opt in to Desktop auto-update checks and staged apply.
`--include-desktop`	`false`	Require matching CLI and Desktop artifacts for the current platform.
`--kit <name>`	Empty	With `--changelog`, filter one public Kit: `engineer` or `marketing`.
`--registry-url <url>`	Environment or release default	Override the signed binary release root.
`--target <targets>`	Empty	With `--changelog`, filter `all`, `cli`, `app`, `kits`, `engineer`, or `marketing`; repeatable/comma-separated.
`--version <version>`	Channel pointer	Resolve an exact binary version.

Shared flags are described in CLI conventions.

Check, dry-run, and apply

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

Check fetches and verifies the signed channel pointer and immutable manifest, but does not download artifacts. Availability failures become status=unknown, usually with reason=release_check_unavailable, and still exit 0.
Dry-run downloads the platform artifacts, verifies them, writes a temporary staging directory, and removes it. It does not replace the CLI or write the persistent binary cache/pending state.
Apply requires --yes. It verifies Ed25519 signatures, the channel pointer's manifest digest, manifest compatibility, and each artifact's declared size and SHA-256 before replacement.

--enable-auto-update and --disable-auto-update write ~/.agentkit/config.yaml without requiring --yes, then continue with a check unless --dry-run was also selected. They do not apply the binary in the same invocation, even when --yes is also present.

Replacement and Desktop behavior

For an unmanaged CLI-only update, artifacts are staged under ~/.agentkit/cache/binaries/<version> (AGENTKIT_HOME changes the base):

On macOS and Linux, AgentKit writes a sibling temporary executable, renames the old executable to a temporary backup, installs the candidate, and removes the backup after success. If the final rename fails, it attempts immediate restoration.
On Windows, CLI-only replacement is staged for a detached trusted helper to finish after the current process exits. When another process still holds ak.exe, the helper renames the live executable aside, installs the verified candidate, and restores the prior executable if replacement cannot complete. Later update attempts remove only recognized inactive updater artifacts; active pending state and unrelated lookalike files are preserved.
With --include-desktop --yes on a supported platform, matching CLI and GUI artifacts are staged as one pending transaction. On macOS and Linux, restart the AgentKit Desktop app to reverify and complete it. On Windows x64, a trusted handoff helper commits the verified swap after the parent process releases the executables.

After successful replacement there is no retained user-facing rollback copy. If verification or replacement fails, keep the reported staging/pending paths, rerun the check, and use the package manager when ownership is reported. Do not manually swap unverified bytes.

Changelog mode

ak self-update --changelog
ak self-update --changelog --target cli --json

Changelog mode fetches verified catalog/body data and is read-only. It cannot be combined with update, settings, --version, or --yes flags.

Output and streams

Human results are written to stdout. Normal JSON success uses kind=self_update with these data fields:

available, status, reason, current_version, latest_version,
auto_update, channel, channel_source, applied, restart_required, message,
updated_paths, pending_path, staging_dir, install_manager, upgrade_command

channel_source names the input that selected the channel: flag, preference, binary, or default. Human output prints the same source next to the channel. Optional fields are omitted when empty. Changelog JSON instead uses kind=self_update.changelog.

Command-level validation and apply failures return before the success renderer. In --json mode they, and flag-parse errors (exit 2), end stderr with the shared error envelope. Treat process status as the failure signal and capture stderr for human mode.

Exit status

Exit	Meaning	Safe next step
`0`	Check, managed-install report, settings change plus check, verified dry-run, changelog, or apply completed. `status=unknown` is also exit `0`.	Inspect `status`, `reason`, `applied`, and `restart_required`.
`1`	Config, manager detection, network apply, signature/digest, compatibility, artifact, staging, replacement, or changelog availability failed.	Do not bypass verification; use the reported manager command or retry the signed flow.
`2`	Arguments, flags, an unsupported channel, channel combinations, or changelog filters were invalid.	Correct the invocation.

There is no decline exit because the command never prompts.