3.0.0-beta.15). Features may change before the next stable release.Switch to stable →ak kit
ak kit install
Install a kit into an explicit runtime, scope, and delivery mode with reviewed output and recovery.
Use ak kit install to resolve a kit and emit it into a runtime or build
directory. It is the install-oriented entry point for the same implementation
used by ak kit init.
Syntax
ak kit install <kit-name><kit-name> is the single installable kit ID. On an interactive TTY, omitting
it can open the setup wizard; a scripted invocation without it fails.
Before you run
Released kits resolve from the authenticated remote registry by default. For
remote examples, replace <channel> with the release channel selected in the
docs header. Omitting --channel selects stable; paid kits require a valid
CLI session and entitlement before preview or writes.
ak whoami
ak licensesRemote resolution can contact the registry, refresh saved authentication, download a runtime-specific artifact, and populate the verified cache. A fully verified warm cache can cover some offline failures, but an explicit entitlement denial does not fall back to cached content.
Use --local --kits-dir <dir> only for an intentional development or CI source.
Grok Build is a signed registry target for normal Kit installation. Use
--local --kits-dir <dir> only when intentionally selecting a development or
CI source. AgentKit emits Grok runtime files and lifecycle metadata; Grok
still owns authentication, model, trust, permission, and sandbox behavior.
Arguments
<kit-name> is the single installable Kit ID. It is required in scripted or
non-interactive use; an interactive TTY can open the setup wizard when it is
omitted.
The command has no alias.
Options
| Option | Default | Effect |
|---|---|---|
--accept-risks <token> | Empty | With --fresh, accept exactly the safety risks a previous plan listed, by its printed token. |
--beta | false | Shorthand for --channel beta. |
--build-only | false | Build into a local output directory instead of installing. |
--channel <channel> | stable | Select the remote kit channel. |
--exclude-skills <names> | Empty | Install every Skill except a comma-separated set. |
--force | false | Authorize a bounded overwrite of an occupied target. |
--fresh | false | Reset one selected installed target to kit-only output after confirmation and a verified snapshot. Not with --force, --no-backup, --build-only, or --out. |
-g, --global | false | Use the runtime's user scope instead of the current project. |
--kits-dir <dir> | Empty | Select an explicit local kit source. |
--local | false | Use the explicit local source instead of the registry. |
--no-backup | false | Skip applicable pre-install snapshots and takeover protection. |
--out <dir> | Empty | Set the build or export output root. |
--registry-url <url> | Environment or release default | Override the registry base URL. |
--remote | true | Use the authenticated remote registry; passing it explicitly is unnecessary. |
--select-skills | false | Choose Skills interactively; requires a TTY. |
--skills <names> | Empty | Install only a comma-separated set of Skills. |
--switch-to-plugin | false | Select Claude Code plugin delivery at the chosen scope. |
--target <ids> | claude-code | Select one or more comma-separated emitter targets, including dsh, grok, and pi; generated command facts may lag newly registered Kit projection targets. |
--version <version> | Channel latest | Select a remote kit version. |
--zip | false | With --target portable, also write one uploadable ZIP per Skill. |
--skills, --exclude-skills, and --select-skills are alternative selection
modes. --out requires --build-only for production targets. Export-only
targets such as portable imply build mode when --out is set. Shared flags
are documented in CLI conventions.
Choose the route
| Route | Selector | Main destination |
|---|---|---|
| Project-native Claude Code | --target claude-code | Project .claude surfaces plus .agentkit lifecycle metadata. |
| User-native Claude Code | --target claude-code --global | User Claude surfaces plus AgentKit lifecycle data. |
| Project Claude plugin | --target claude-code --switch-to-plugin | Project ak-<kit> plugin. |
| User Claude plugin | --target claude-code --global --switch-to-plugin | ak-<kit> under the configured user plugin root. |
| Project or user Codex | --target codex with optional --global | Project or user .agents and .codex surfaces. |
| Project or user Cursor | --target cursor with optional --global | Project or user .cursor surfaces. |
| Project or user DeepSeek Harness | --target dsh with optional --global | Project .dsh/skills/ or ${DSH_HOME:-~/.dsh}/skills/ plus lifecycle metadata. |
| Project or user Grok Build | --target grok with optional --global | Project .grok or $GROK_HOME (default ~/.grok) plus lifecycle metadata. |
| Project or user Pi | --target pi with optional --global | Project .pi/{skills,agents,rules,extensions} or the active Pi coding-agent profile. |
| Project or user Oh My Pi | --target omp with optional --global | Portable ak-<slug> Skills under project .omp/skills or the resolved OMP profile root, plus the corresponding OMP surfaces. |
| User AGY | --target agy --global | Global Gemini/AGY Skills plus optional Agents under ~/.gemini/config/agents/<name>/agent.md, projected from the signed remote claude-code package with runtime-compatible frontmatter. |
| Build or export | --build-only --out <dir> or --target portable --out <dir> | The selected output directory. |
A project install refuses a route that resolves to the user-level install, such as
a project directory that is your home directory, a project .agentkit that is
your AgentKit home, or a project .claude, .codex, or Pi extension that is the
matching user-level root. The check covers every selected target, runs before
any Skill picker, preview, lock, snapshot, or write, and exits 6. Re-run with
--global to manage the user-level install, or run from another project
directory. Build and export routes are not checked.
Project and user installs can coexist. Claude native and plugin delivery are separate modes within one scope; switching modes is an explicit, snapshot-backed transition.
portable is export-only. Without --out, install shares the early exit 1
from the init implementation before preview, prompts, source resolution,
lifecycle work, or disk writes:
init: target "portable" is export-only and has no install mode; re-run with --out DIR to export a standalone build--out implies build mode and preserves the remote source default. Explicit
--build-only --out uses the local-development source default. Add --zip when
a portable export should also produce one uploadable ZIP per Skill. AGY is
global-only and is not a refresh lifecycle peer.
Because install uses the init implementation, OMP behavior is identical.
Projected Skill directories and top-level SKILL.md names use ak-<slug>, while
body aliases such as /ak:cook and $ak:cook and the ak run <kit>/<skill> --target omp selector stay unchanged. Trusted project OMP also
discovers project .agents/skills: project .omp/skills shadows a colliding
project .agents/skills copy for a project install, while project
.agents/skills shadows the OMP profile copy when a global install is used from
that project. The command warns and continues; it does not skip OMP emission,
delete or rewrite either Skill, alter .agents or OMP settings, require
--force, or return exit 6.
Examples
# Project-native Codex install from the release source.
ak kit install engineer --target codex --channel <channel>
ak kit install engineer --target pi --channel <channel>
# Explicit user Claude plugin install.
ak kit install engineer --target claude-code --global --switch-to-plugin --channel <channel>
# Intentional unattended install.
ak kit install engineer --target codex --yes --no-interactive --json --channel <channel>
# Local development source with a selected Skill set.
ak kit install engineer --local --kits-dir ./kits --skills ak-cook,ak-plan --yes
# Grok project install from an explicit local development source.
ak kit install engineer --local --kits-dir ./kits --target grok --yes
# Portable export with one uploadable ZIP per Skill.
ak kit install engineer --target portable --out ./ak-export --zipConfirmation behavior
On an interactive TTY, install mode previews the destination and asks
Continue? [y/N]:. Only y or yes proceeds.
--json, --no-interactive, and non-TTY stdin skip the prompt and can write
without --yes. Use --yes in automation to make mutation intent explicit.
--fresh is the exception: a scripted run without --yes stops with exit 3.
A TTY decline currently exits 1. Build and export routes do not show the
install preview.
Output and streams
Human progress, destination preview, and confirmation use stderr. The final summary uses stdout and reports the kit, output path, file count, install mode, scope, Hook summary, warnings, and recovery information when present.
With --json, stdout contains a versioned envelope with kind=kit.init and
command data under data. Unless --quiet is set, stderr also contains raw
status records with action, kit, destination, and status; status is
preview before writes and complete after success.
Success data includes kit, target, optional targets, mode,
installMode, scope, outDir, filesWritten, success, and optional Skill,
Hook, warning, transition, configuration, and recovery fields. JSON-mode
failures, including flag-parse errors (exit 2), end stderr with the shared
error envelope: schema_version, error,
error_code, and exit_code.
Human and JSON execution errors show the recovery reason by default, with
known secret shapes and URL query strings redacted and paths preserved.
--verbose can expose the raw underlying error; review it before sharing.
Hook projection data can also include optional hooksDropped,
droppedHookSummaries, hookMatchersNarrowed, and narrowedHookSummaries.
Human output separates Hook groups not projected: <count> group(s) - see warnings from Hook matchers narrowed (some tool matches unsupported on this target): <count> matcher(s) - see warnings. A disclosed
drop or narrow does not make the install fail.
Exit status
| Exit | Meaning |
|---|---|
0 | The selected install, build, or export completed. |
1 | Validation, source, authentication, entitlement, destination, emission, write, or TTY-decline failure. Current runtime also uses 1 for local-kit-not-found and occupied-target cases. |
2 | Cobra rejected flags, arguments, or a flag combination. |
3 | A shared cancellation or interrupt path returned cancellation, or a --fresh reset was not run because it needs confirmation or acceptance of listed risks. |
4 | Another kit lifecycle mutation holds the lock. |
6 | The project route resolves to the user-level install; re-run with --global or from another project directory. |
Command help reserves 5 for a missing local kit and 6 for an occupied
target, but those two install errors currently fall through to exit 1. Only
the user-level route refusal is classified as 6; do not branch on 5 or 6
for the other cases until runtime classification changes.
Effects, safety, and recovery
Installation can write runtime-native files, ownership and lifecycle metadata, project configuration, Hook scripts, Skill directories, mode-transition state, and user runtime configuration. A user-scope Codex install can register the AgentKit MCP runtime.
Unknown and user-modified files are preserved unless a supported operation and
--force authorize a bounded overwrite. AgentKit normally snapshots affected
owned surfaces before forced overwrites or mode transitions. Some snapshots can
be restored with ak backups restore; project-local output can instead report
a manual snapshot data directory outside normal restore scope.
ak backups show <id>
ak backups verify <id>--fresh resets one selected target to kit-only output: it removes custom and
unrecorded files inside the kit's own lifecycle root after one confirmation and
a verified snapshot, unlike --force, which keeps them. The plan, consent,
risk tokens, refusals, and recovery output are the same as for
ak kit init --fresh.
Follow the reported recovery command or manual path. Do not delete a runtime home or assume every snapshot is a full or transactional backup.
Limitations and related commands
Codex cannot project every Claude command, Hook matcher, or status-line feature.
Review warnings after a successful install. Engineer projects one fully dropped
task-state PostToolUse group and two shared narrowed matchers; Marketing
projects three narrows and no full drop. Supported matcher atoms remain active.
On Windows, eligible Codex .cjs Hooks inside the Codex home can use owned
.cmd shims for paths containing spaces; external, metacharacter, or unsafe
non-ASCII paths remain limited and are reported.
A wrapper-managed Codex home may alias only its final hooks leaf to canonical
~/.codex/hooks, using a POSIX symlink or a Windows directory junction; Hook
commands, writes, rollback, and ownership use that canonical identity. Linked
parents and noncanonical targets remain unsupported.
ak kit inituses the same installation implementation.ak kit refreshreconciles an existing route and removes stale clean owned output.ak kit uninstallpreviews or removes installed owned output.- Complete command facts
- Install kits safely
- Kit installation troubleshooting
hooksDeferred is a subset of hooksDropped: the harness bridge defers that subscription, which does not mean the runtime cannot express it. Read the summary to distinguish deferred from unsupported groups.