ak versions

Inspect the ak binary, every installed kit destination, and Claude-plugin skills, with per-destination provenance and check states.

Use ak versions to inspect the running CLI build, every installed kit destination, and the skills discovered under the Claude plugin install root. It is an inventory command, not an updater.

Usage

ak versions

The command accepts no positional arguments.

Options

Flag	Default	Description
`--cache-ttl <duration>`	`1h0m0s`	Decide when existing registry cache data is stale. Nonpositive values reset to one hour.
`--local-only`	`false`	Use only local install evidence. Makes no network requests and writes no cache.
`--remote-only`	`false`	Skip local kit and skill enumeration. Reserved for a configured versions registry endpoint.

--local-only and --remote-only are mutually exclusive. Shared output flags are described in CLI conventions. The command never prompts, and --yes has no effect.

Before you run

Local enumeration reads:

binary version, commit, and build date compiled into ak;
the install receipts of every kit destination for the current project and the global scope, giving one record per runtime, scope, and delivery mode;
skill manifests under AGENTKIT_PLUGIN_DIR/<kit>/skills/, or ~/.claude/plugins/<kit>/skills/ by default.

Cache and source trees are not installed kits, so they do not appear as rows.

In default mode, the command checks the signed binary release metadata and resolves the latest kit versions from the authenticated registry manifest (metadata only, nothing is downloaded or installed). Results are cached in ~/.agentkit/cache/registry/index.json (under AGENTKIT_HOME when set). A fresh cache entry is reused; a stale one is kept as an offline fallback and reported with check state stale. Missing, corrupt, or unreadable cache data is treated as a miss.

--local-only makes zero network requests and writes no cache; every row then reports check state not_checked. --remote-only returns binary identity and empty kits and skills arrays.

Examples

ak versions
ak versions --local-only
ak versions --json
ak versions --cache-ttl 30m

Output and streams

Human stdout is a table with one row per destination. Wide terminals show TYPE, NAME, SOURCE, INSTALLED, AVAILABLE, HEALTH, and STATUS, so the source version, the recorded registry release, and the available registry release are labeled separately. Each kit row also lists its destination and, when known, its channel and channel source. Missing optional values print as unknown.

JSON success uses an outer kind=versions envelope (envelope schema_version 1). data has its own inventory schema_version, which is now 2:

data.schema_version: 2
data.binary: version, commit, date, latest, check_state, version_state
data.kits[]: kit, runtime, scope, delivery_mode, destination,
  source_version, registry_version, available_version, origin, channel,
  channel_source, required_cli_version, emitted_by_cli, receipt_recorded,
  health, last_emit, check_state, version_state, compatibility
data.skills[]: kit, name, version
data.registry: cached_at, stale, optional stale_age, check_state, optional reason

check_state is not_checked, checked, offline, failed, or stale. version_state is unknown, dev, current, update_available, or ahead. compatibility is satisfied, requires_upgrade, or unknown, and health is ok, modified, incomplete, or unknown. The arrays are present even when empty, and missing optional kit fields are null. Version 1 field names such as data.kits[].name and version are gone, so update parsers that read them. JSON-mode failures, including flag-parse errors (exit 2), end stderr with the shared error envelope.

Exit status

Exit	Meaning	Safe next step
`0`	Inventory completed. Cache miss, corruption, staleness, or an offline or failed lookup is nonfatal.	Read each row's `check_state` and `registry.stale` before interpreting available versions.
`1`	Local kit or install-root enumeration failed, such as an unreadable directory.	Fix access to the reported root or use the appropriate source override.
`2`	Flags were invalid, durations could not be parsed, both source flags were set, or an argument was supplied.	Correct the invocation.

The command does not apply, replace, or remove anything. Default mode can update the registry cache; --local-only does not. Use an update command only after reviewing the relevant lifecycle.