ak kit

Choose the correct kit discovery, validation, install, refresh, path, repair, or uninstall operation.

Use ak kit as the entry point for content-kit lifecycle commands. The group itself is read-only: running it without a subcommand prints help and exits 0.

Usage

ak kit <subcommand>

ak kit --json prints group help rather than a JSON result. Put shared flags on a runnable leaf command and follow that command’s output contract. Shared flags are listed in CLI conventions.

Choose a subcommand

Goal	Command	Source and effect
Browse local kit manifests	`ak kit list-kits`	Reads `$AGENTKIT_KITS_DIR` or `./kits`; `--kits-dir` overrides it.
Validate local manifests	`ak kit validate [kits-dir]`	Reads `kit.yaml` files and reports violations.
Resolve and emit a kit	`ak kit init <kit-name>`	Remote registry by default; can install to a runtime route or build/export directory.
Use the install-oriented entry point	`ak kit install <kit-name>`	Same implementation and flags as `ak kit init`.
Reconcile an installed route	`ak kit refresh <kit-name>`	Re-emits the route and removes stale AgentKit-owned output within lifecycle rules.
Resolve the user Claude plugin path	`ak kit install-path <kit-name>`	Read-only path calculation; it does not cover every target or scope.
Preview or remove an installed kit	`ak kit uninstall <kit-name>`	`--dry-run` previews; apply removes selected owned paths after confirmation/yes.
Repair mixed Claude install modes	`ak kit repair-install-mode`	Requires an explicit mode choice and confirmation; writes a recovery snapshot.

init and install are equivalent entry points, not different delivery modes. Use refresh when the route is already installed. Use ak init to register an existing project and ak new to create a new project; neither is a substitute for selecting a kit route.

Separate source, target, scope, and delivery

For install and refresh operations, decide four independent dimensions:

Source: authenticated remote release by default for published targets, with --channel <channel> matching the docs header, or explicit --local --kits-dir <dir> for development and CI.
Target: claude-code, codex, cursor, dsh, grok, pi, or omp for a released registry package; agy for the global projection sourced from the signed claude-code package; or portable for export with --out.
Scope: current project by default, or user scope with --global.
Delivery: native runtime output, Claude plugin mode with --switch-to-plugin, or build/export output.

ak kit init engineer --target grok --channel <channel>
ak kit refresh engineer --target grok --channel <channel>

Use --local --kits-dir <dir> only when intentionally testing a development or CI source. AgentKit emits Grok runtime files and lifecycle metadata; Grok still owns authentication, model, trust, permission, and sandbox behavior.

Network, authentication, and cache behavior

list-kits, validate, install-path, uninstall, and repair-install-mode operate on local state. Remote init, install, and refresh can contact the registry, renew the CLI session, enforce entitlement, download a target artifact, and populate the verified cache before emitting files. Paid kits require a valid CLI session and active grant.

ak whoami
ak licenses

Local source flags are an explicit development route, not an authentication or entitlement fallback.

Treat each mutation contract separately

init, install, and refresh show an interactive destination preview, but JSON, --no-interactive, or non-TTY stdin can proceed without --yes. Use --yes in intentional automation.
uninstall is preview-first and returns without mutation when confirmation is missing.
repair-install-mode requires an exact keep choice and confirmation.
Force and backup flags are command-local. They do not authorize deleting arbitrary unknown files.
Lifecycle mutations coordinate through locks and can create bounded recovery snapshots before destructive changes.

Do not infer one leaf command’s exit or JSON behavior from another. For example, install routes use a kind=kit.init success envelope and can emit status records on stderr, while install-path uses kind=kit.install_path and has no mutation status stream.

Review unsupported hook disclosure

init, install, and refresh distinguish fully unsupported Hook groups from partially narrowed matchers. Human output prints Hooks dropped (unsupported on this target) or Hook matchers narrowed (some tool matches unsupported on this target). JSON success data can include optional hooksDropped, droppedHookSummaries, hookMatchersNarrowed, and narrowedHookSummaries. hooksDropped counts unsupported Hook groups, not individual handler occurrences within a group, on both Codex and Pi; droppedHookSummaries is no longer a one-to-one mirror of the warning list.

A disclosed drop or narrow does not make the installation fail. A full drop is not installed; a narrow keeps handlers active on supported matcher atoms. Review the warnings before treating the target route as behaviorally equivalent to its source runtime — and, on Pi, the notices too. On Pi, a deferred Hook group (deferred subagent lifecycle) and an omitted Agent model: tier arrive as uncounted notices rather than warnings, so a Pi install that reports zero warnings can still carry deferred behavior; check notices as well as hooksDropped before assuming parity.

Pi also reports a counted warning when an incoming Kit Agent would redefine a runtime Agent name already declared by another Kit or by a foreign file in the same Agents root. Pi resolves Agents by their frontmatter name:, while AgentKit emits Kit-scoped filenames, so installing two Kits that define the same role is now disclosed as a warning rather than going unreported.

Verify an operation

After an install or refresh, review target warnings, reopen the runtime, and invoke one installed skill. After uninstall or repair, inspect any reported snapshot before changing more files:

ak backups show <id>
ak backups verify <id>

On this page