2.4.1-beta.1) — updated automatically on every beta release.Switch to stable →CLI commands
ak new
Bootstrap a new AgentKit project
Create a new AgentKit project at ./<project-name>/. Every file the command writes is recorded in <project>/.agentkit/ownership.json so future ak update / ak uninstall can act precisely on AK-owned files. A --template / --kits preinstall fetches from the authenticated remote registry by default, mirroring ak kit init.
Who it's for: Both: power devs (--no-interactive --json) and non-tech users (defaults).
When to use it: Starting a fresh AK project. Use ak init instead to onboard an existing directory.
What changes on disk: Creates ./<project-name>/ and writes the ownership manifest plus any seed / kit content. Snapshots prior state via ak backups only when the target dir already contains an AgentKit ownership manifest.
Usage
ak new <project-name> [flags]Examples
ak new myproj # greenfield bootstrap
ak new myproj --template engineer # remote is the default; paid kits require `ak login`
ak new myproj --template core --local --kits-dir ./kits # local development seed, no network
ak new myproj --force # overwrite an AK-owned project
ak new myproj --json # script-friendly envelopeFlags
| Flag | Description |
|---|---|
--channel string | Remote registry channel (beta requires explicit opt-in) (default "stable") |
--force | Overwrite an existing target directory |
-h, --help | help for new |
--json | Emit machine-readable JSON (implies --no-interactive) |
--kits string | Comma-separated list of kits to preinstall |
--kits-dir string | Kits source directory (default: ./kits or $AGENTKIT_KITS_DIR) |
--local | Preinstall --template/--kits from the embedded/local kit source instead of the remote registry (dev/CI). Paid kits still require remote access (the default) or an explicit --kits-dir. |
--no-interactive | Disable interactive prompts (CI-safe) |
-q, --quiet | Suppress non-error output on stderr |
--registry-url string | AgentKit registry base URL (default: $AGENTKIT_REGISTRY_URL, then dev/staging https://staging.agentkit.best or release https://agentkit.best) |
--remote | Preinstall --template/--kits from the authenticated remote registry (default; use --local for the embedded/dev source) (default true) |
--template string | Bootstrap from a single kit (mutually exclusive with --kits) |
-V, --verbose | Extra diagnostic output on stderr (loses to --quiet) |
--version string | Remote kit version (defaults to channel latest) |
-y, --yes | Assume yes for all prompts |
Output modes
| Mode | Behavior |
|---|---|
pretty | default on TTY (colors, ASCII markers) |
plain | auto when stdout piped or --no-interactive |
json | --json (single-object envelope, NDJSON-safe) |
Exit codes
| Code | Meaning |
|---|---|
0 | success |
1 | runtime error |
2 | invalid flags |
3 | user-cancel (SIGINT, prompt-cancel) |
2 | invalid flags or project name |
6 | target directory already exists without --force |
Related commands
ak— AgentKit CLI