--- title: "AgentKit documentation" description: "Getting started and legacy CLI documentation." --- # AgentKit documentation This page is the getting-started on-ramp. The complete reference — CLI commands, kit configuration, skills, and workflows — lives at [https://docs.agentkit.best](https://docs.agentkit.best). ## AgentKit CLI > **`ak` is the new AgentKit CLI** — the successor to the legacy ClaudeKit `ck` CLI. It ships as a single native binary for macOS, Linux, and Windows (no Node.js or Bun required) and manages AgentKit workflow kits for 7 agent runtimes: Claude Code, Codex, Cursor, Antigravity, Pi, Oh My Pi, and DeepSeek Harness. Coming from `ck`? Jump to [Migrate from the legacy ck CLI](#migrate-from-the-legacy-ck-cli). ## Installation ### macOS / Linux ```bash curl -fsSL https://agentkit.best/install.sh | sh ``` If your network blocks the product domain, use the trusted direct release alias: ```bash curl -fsSL https://releases.agentkit.best/install.sh | sh ``` Both commands run the same release-managed installer and preserve the signed channel-pointer, pinned bootstrap-verifier, and archive-checksum chain. Never disable verification to work around a network or endpoint-protection error. The installer detects your OS/architecture, downloads the current release for the `stable` channel, verifies it (SHA-256) against the signed release manifest, and installs `ak` into `~/.local/bin`. It is idempotent and always resolves the **latest** release on the channel — re-run the same one-liner anytime to upgrade in place (it overwrites the existing binary; if you already have the latest, it simply reinstalls the same version). Customize with environment variables: ```bash # Install to a custom directory curl -fsSL https://agentkit.best/install.sh | AK_INSTALL_DIR="$HOME/bin" sh # Install the latest public beta build (default channel: stable) curl -fsSL https://agentkit.best/install.sh | AK_CHANNEL=beta sh # Pin an exact version curl -fsSL https://agentkit.best/install.sh | AK_VERSION=1.0.0 sh ``` ### Windows (PowerShell) ```powershell irm https://agentkit.best/install.ps1 | iex ``` If your network blocks the product domain, use the trusted direct release alias: ```powershell irm https://releases.agentkit.best/install.ps1 | iex ``` The direct alias uses the same signed verification chain as the primary command. Keep Windows security controls enabled; a security warning is a failed install, not a prompt to add an exclusion. Installs `ak.exe` into `%USERPROFILE%\bin` and adds that directory to your user `PATH` automatically — open a **new** terminal afterward. Like the shell installer it is idempotent and resolves the latest release on the channel — re-run it to upgrade in place. Customize before piping: ```powershell # Install the latest public beta build (default channel: stable) $env:AK_CHANNEL = "beta"; irm https://agentkit.best/install.ps1 | iex # Pin an exact version $env:AK_VERSION = "1.0.0"; irm https://agentkit.best/install.ps1 | iex # Install to a custom directory $env:AK_INSTALL_DIR = "$env:USERPROFILE\Programs\AgentKit"; irm https://agentkit.best/install.ps1 | iex ``` ### Verify the installation ```bash ak --version ak doctor ``` `ak doctor` checks your environment and reports anything that needs attention. --- ## Authenticate On the CLI, sign in with your **email** or an **API key** — both open a CLI session. Find your user API key in your [account dashboard](https://agentkit.best/account). **Email** — sends a one-time code (OTP) you paste back when prompted (recommended for local use): ```bash ak login --email you@example.com ``` **API key** — a user API key from your web profile, ideal for CI and non-interactive use: ```bash ak login --api-key ak_live_... --no-interactive ``` Verify your session and entitlements: ```bash ak whoami ak licenses ``` > **License keys activate the AgentKit Desktop App — not the CLI.** `ak login --license-key ak_license_...` performs *device activation* for the desktop app rather than a CLI session. On the CLI, use `--email` or `--api-key`. ### Where credentials are stored AgentKit uses `~/.agentkit` as its home directory by default; set `AGENTKIT_HOME` to use another location. Credentials are stored under `$AGENTKIT_HOME/auth/`. The schema-v2 session document is `$AGENTKIT_HOME/auth/session.json`, with separate logical `cli` and `app` slots for the CLI and Desktop App in the same file. - Email OTP login stores a short-lived CLI access/session token and rotating refresh credential in `session.json`. The one-time code is not retained. - API-key login stores a short-lived CLI session in `session.json` and the raw API key in the sibling `$AGENTKIT_HOME/auth/api-key` file. AgentKit uses the retained key to mint a new CLI session automatically when the current session expires or is rejected. A license key is not retained. - These files are plaintext: they are not encrypted or backed by the OS keychain. On macOS and Linux, AgentKit sets the auth directory to mode `0700` and credential files to `0600`. On Windows, it applies a protected DACL granting access only to the current user. These filesystem access controls are the confidentiality boundary, so do not copy, commit, or share the files. `ak logout` removes the `cli` slot and retained API key under a shared mutation lock; missing credentials still count as a successful logout. For email sessions, remote revocation is best-effort and happens after local removal. Logout preserves the separate Desktop App `app` slot, which Desktop sign-out clears separately. --- ## Install a kit Once authenticated, install a kit for your coding agent: ```bash # Engineer kit for Claude Code, available in every project ak kit init engineer --target claude-code --global # Marketing kit ak kit init marketing --target claude-code --global # Codex as the target agent ak kit init engineer --target codex --global # Cursor as the target agent ak kit init engineer --target cursor --global # Pi as the target agent ak kit init engineer --target pi --global # Oh My Pi (omp) as the target agent ak kit init engineer --target omp --global # DeepSeek Harness (dsh) as the target agent ak kit init engineer --target dsh --global # Grok as the target agent ak kit init engineer --target grok --global # Preview: Google Antigravity CLI (agy), global installs only, not an `ak update` target ak kit init engineer --target agy --global ``` AgentKit v3.0.0 ships kit packages for 7 agent runtimes, so `ak kit init` and `ak update` target them: Claude Code (`claude-code`), Codex (`codex`), Cursor (`cursor`), Pi (`pi`), Oh My Pi (`omp`), DeepSeek Harness (`dsh`) and Grok (`grok`). Their support level comes from the [v3.0.0 certification matrix](https://github.com/bestagentkits/agentkit/blob/v3.0.0/docs/conformance/runtime-support-matrix.yaml): | Runtime | Support level | macOS | Windows | Linux (WSL) | | --- | --- | --- | --- | --- | | Claude Code | Certified | pass | pass | pass | | Pi | Certified | pass | pass | pass | | Oh My Pi | Certified | pass | pass | pass | | DeepSeek Harness | Certified | pass | pass | pass | | Codex | Partial | pass | assumed | pass | | Cursor | Preview | assumed | assumed | assumed, latest run failed | | Grok | Preview | no measured run | no measured run | no measured run | Antigravity (`agy`) is in **preview**: a projection format for global installs only, with no kit package in the release, so `ak update` does not target it. Its cells are assumed on every OS. **Assumed** means the runtime ships on source and unit tests and is not certified by a measured run. Every certified pair passed a measured install, discovery, invocation and uninstall run. If an assumed runtime misbehaves, [open an issue](https://github.com/bestagentkits/agentkit/issues/new). `ak doctor --check runtime_support_tier` shows the tier of each runtime installed on your machine. Install only part of a kit with skill selection: ```bash ak kit init engineer --target claude-code --global --skills ak-cook,ak-plan ak kit init engineer --target claude-code --global --exclude-skills ak-video ``` `--select-skills` opens an interactive picker. In Claude Code, kit skills are invoked with the `/ak-` slash prefix (Codex uses `$ak-`): ```text /ak-cook # develop a new feature /ak-plan # scan, analyze, and plan an implementation /ak-fix # fix bugs with root-cause analysis /ak-ask # ask anything with project-aware context ``` Browse available kit names with `ak kit list-kits`; use `ak versions` to inspect local installed versions. --- ## Use kits in other coding agents (portable target) The 7 runtimes above get native, per-runtime kits. Working in a different coding agent — **OpenCode, Grok, GitHub Copilot**, or similar? Install any kit with the `portable` target: ```bash # Portable export of the Engineer kit for any coding agent ak kit init engineer --target portable # Marketing kit, portable profile ak kit init marketing --target portable ``` The `portable` target emits a neutral, best-effort profile: skill and agent instructions are rewritten to use generic capability language (*read file*, *edit file*, *search files*, *run shell command*) instead of Claude Code- or Codex-specific tool names, and subagent guidance avoids prescribing a named model. It writes a portable kit folder you then import into your agent of choice. > **Portable is a temporary bridge, not native support.** It is the best option available today for agents AgentKit does not yet support natively — expect roughly **80–90%** of the capability you get from the native kits, with no runtime guarantees. The native runtime outputs are unchanged and remain the fully supported path. We're actively deepening per-agent integration. As dedicated adapters land for specific harnesses, those agents will graduate from the portable profile to first-class support with higher fidelity and a smoother experience. --- ## Update ```bash # Check for a binary update, then apply it ak self-update --check ak self-update --yes # Refresh an installed kit and remove stale generated files ak kit refresh engineer --global --yes # Preview updates to an AgentKit-managed project, then apply them ak update ak update --yes ``` `ak self-update` updates the `ak` binary; `ak update` refreshes AgentKit-owned project content; and `ak kit refresh --yes` refreshes an installed runtime kit, including removal of stale generated files. `ak self-update --dry-run` and `ak update --dry-run` are read-only previews. `ak kit init` uses an interactive confirmation (or `--yes` for scripts) and preserves unknown or user-modified files by default; kit refreshes snapshot tracked content before rewriting it. --- ## Migrate from the legacy ck CLI The legacy `ck` CLI (the `claudekit-cli` npm package) is deprecated. `ak migrate` is a transitional, one-time safety net for taking over recognized ClaudeKit installs; it is not part of the normal kit update flow: ```bash # Preview the migration — read-only, this is the default ak migrate --from=ck # Apply it non-interactively (CI-friendly) ak migrate --from=ck --dry-run=false --yes --no-interactive ``` `ak migrate` is read-only until you pass `--dry-run=false --yes`, and it snapshots state before writing so you can `ak migrate rollback` if needed. Prefer to do it by hand? The manual steps below cover the same ground: **1. Find and remove the old `ck` install.** A stale `ck` earlier on your `PATH` can keep old scripts running ClaudeKit even after AgentKit is installed. ```bash # macOS / Linux — inspect every ck on PATH, then remove the npm package which -a ck npm uninstall -g claudekit-cli # or: bun remove -g claudekit-cli ``` ```powershell # Windows Get-Command ck -All npm uninstall -g claudekit-cli ``` **2. Install `ak`** using the one-liners above, then **authenticate** with your email or API key. **3. (Optional) Keep `ck` as an alias.** The `ak` binary detects when it is invoked as `ck` and behaves identically, so existing scripts keep working: ```bash # macOS / Linux — symlink (future ak updates apply automatically) ln -sf ~/.local/bin/ak ~/.local/bin/ck ``` ```powershell # Windows — copy next to ak.exe, or add a profile function Copy-Item $env:USERPROFILE\bin\ak.exe $env:USERPROFILE\bin\ck.exe ``` Verify the shim resolves correctly: ```bash ak doctor --check ck_shim_collision ``` **Command mapping** | Legacy `ck` command | New `ak` equivalent | |---|---| | `npm install -g claudekit-cli` | `curl -fsSL https://agentkit.best/install.sh \| sh` | | `ck new` | `ak new` | | `ck init` | `ak init` | | `ck update` | `ak update` | | `ck setup` | `ak setup` | | `ck skills` / `ck agents` | `ak skills` / `ak agents` | | `ck doctor` | `ak doctor` | | `ck versions` | `ak versions` | | `ck config` | `ak config` | | `ck uninstall` | `ak uninstall` | | GitHub PAT authentication | `ak login --email ` (or `--api-key `) | | — | `ak kit init --target --global` (kit lifecycle) | | — | `ak self-update`, `ak audit`, `ak gui` (new in `ak`) | --- ## Troubleshooting | Symptom | Fix | |---|---| | `ak: command not found` after install | Ensure the install dir is on `PATH`: `echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc` (or `~/.bashrc`), then open a new shell | | Windows: `ak` not recognized after install | The installer added `%USERPROFILE%\bin` to your user `PATH` — open a **new** terminal | | Windows blocks the installer | Keep security controls enabled. Retry the primary command, then use the trusted direct alias `irm https://releases.agentkit.best/install.ps1 \| iex`. If both fail, stop and contact support with the exact warning. | | Checksum or signature verification failed | Stop the install and retry once. If the primary domain is blocked, use the trusted direct release alias above. Never bypass verification. | | Old ClaudeKit still runs when typing `ck` | A stale `ck` binary sits earlier on `PATH`. Run `which -a ck` (or `Get-Command ck -All`), remove entries that do not point at `ak`, then `ak doctor --check ck_shim_collision` | | `ak login` fails | Confirm your API key matches the one in [/account](https://agentkit.best/account) exactly (no surrounding spaces). For `--email`, check the OTP code hasn't expired. Still stuck? Contact support below | | Kit install fails with a missing entitlement | Your license covers specific kits (Engineer, Marketing, or Bundle). Check `ak licenses` | Need help? Join the [Discord](https://discord.gg/x7SwTSf3wc) or email [support@agentkit.best](mailto:support@agentkit.best). ## Earlier CLI migration guide > **Deprecated:** the ClaudeKit `ck` CLI has been replaced by the new AgentKit `ak` CLI. This page remains for existing installs. New setups should use the **AgentKit CLI (ak)** tab — it includes a step-by-step [migration guide](/docs?tab=ak). ## Method 1: Manual Setup 1. Copy all directories and files of `agentkit-engineer` repo to your project: * `.claude/*` * `docs/*` * `plans/*` * `CLAUDE.md` * `.mcp.json` 2. Go to Google AI Studio and grab the API Key, then open `.mcp.json` to paste into “human-mcp” environment variable. * Recommend: install “Human MCP” with `user` scope to be able to use it in every projects without re-installing: `claude mcp add-json human -s user '{"command": "npx", "args": ["@goonnguyen/human-mcp@latest", "-e", "GOOGLE_GEMINI_API_KEY"], "env": { "GOOGLE_GEMINI_API_KEY": "..." }}'` 3. Start Claude Code in your working project: `claude` (or `claude --dangerously-skip-permissions`) 4. Run command: `/docs:init` to trigger CC scan and create specs for the whole project. You will see some markdown files generated in `docs` directory, such as “codebase-summary.md”, “code-standards.md”, “system-architecture.md”,... 5. Now your project is ready to start development, explore these commands: * `/cook` : develop new feature * `/fix:fast` : fix minor bugs (fast mode) * `/fix:hard` : fix hard bugs * `/plan` : let CC scan, analyze and plan for implementing something * `/bootstrap` : CC will help you bootstrap any new project step by step * `/brainstorm` : brainstorm with CC about anything with project-aware context * `/ask` : just ask any questions * ... --- ## Method 2: Legacy ClaudeKit CLI (ck) ### Installation ```bash npm install -g claudekit-cli ``` ```bash # or with Bun bun add -g claudekit-cli ck --version ``` ### Create a new project ```bash # Interactive mode ck new # With options ck new --dir my-project --kit engineer # Specific version ck new --kit engineer --version v1.0.0 ``` ### Update Existing Project ```bash # Interactive mode ck update # With options ck update --kit engineer # Specific version ck update --kit engineer --version v1.0.0 ``` ### Authentication The CLI requires a GitHub Personal Access Token (PAT) to download releases from private repositories. The authentication flow follows a multi-tier fallback: 1. **GitHub CLI**: Uses `gh auth token` if GitHub CLI is installed and authenticated 2. **Environment Variables**: Checks `GITHUB_TOKEN` or `GH_TOKEN` 3. **OS Keychain**: Retrieves stored token from system keychain 4. **User Prompt**: Prompts for token input and offers to save it securely **Creating a Personal Access Token** 1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic) 2. Generate new token with repo scope (for private repositories) 3. Copy the token **Setting Token via Environment Variable** ```bash export GITHUB_TOKEN=ghp_your_token_here ``` --- ## Ready to migrate? The new `ak` CLI replaces GitHub PAT authentication with email or API-key login, verifies downloads with checksums, and supports 7 agent runtimes: Claude Code, Codex, Cursor, Antigravity, Pi, Oh My Pi, and DeepSeek Harness. Switch to the **AgentKit CLI (ak)** tab for the [migration guide](/docs?tab=ak).