ak kit
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, orompfor a released registry package;agyfor the global projection sourced from the signedclaude-codepackage; orportablefor 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 licensesLocal source flags are an explicit development route, not an authentication or entitlement fallback.
Treat each mutation contract separately
init,install, andrefreshshow an interactive destination preview, but JSON,--no-interactive, or non-TTY stdin can proceed without--yes. Use--yesin intentional automation.uninstallis preview-first and returns without mutation when confirmation is missing.repair-install-moderequires 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>