ak init

Use ak init to register an existing directory as an AgentKit project. It discovers AgentKit-managed files, records their hashes in .agentkit/ownership.json, and does not install a kit.

Syntax

ak init [dir] [options]

Arguments

dir is optional. It resolves to an absolute path; the current directory is used when omitted. The directory must already exist. Use ak new to create a directory. The command has no aliases.

Before you run

Preview first when adopting existing files:

ak init ./my-project --dry-run

The command discovers regular files under the project’s AgentKit, kits, and .claude surfaces. A global AgentKit home nested inside the project is excluded from ownership.

Options

Option	Default	Description
`--docs-dir <path>`	Unset	Persist the documentation directory as `paths.docs`.
`--plans-dir <path>`	Unset	Persist `paths.plans`; use a relative path for compatibility with plan readers.
`--backup`	`false`	Snapshot `~/.claude/` and the project state before init; `backups.enabled: true` in `~/.agentkit/config.yaml` makes this the default.
`--dry-run`	`false`	Classify and report adoption without snapshots, manifest, audit, or registry writes.
`--force`	`false`	Accept existing drift and continue updating ownership records.
`--no-backup`	`false`	Skip every init snapshot, including the one `--force` takes (power users only — data loss risk).
`--project-id <id>`	Directory name	Set the project ID on first initialization.

See CLI conventions for shared output and interaction flags.

Examples

ak init
ak init ./my-project
ak init ./my-project --dry-run --json
ak init ./my-project --force --no-interactive
ak init ./my-project --backup

TTY and confirmation behavior

A human TTY opens a one-step wizard unless --json, --quiet, or --no-interactive is set. Enter confirms; q, Esc, or Ctrl-C cancels before initialization and currently exits 1.

--yes alone does not bypass the wizard. JSON, quiet, noninteractive, and non-TTY execution skip the prompt and write immediately unless --dry-run is set.

A re-run verifies every tracked hash. Drift exits 6 unless --force is used. Force accepts and reports the drift; it does not overwrite the modified file. Newly discovered managed files can then be added to ownership.

Dry-run writes nothing and takes no snapshot. A normal run takes no snapshot by default; --backup or backups.enabled: true captures ~/.claude/ and the project state before drift verification, and --force captures the project ownership state only. Either snapshot happens before drift verification, so an exit 6 can still leave a new recovery snapshot when one was requested.

Output and streams

Human/scripted success is written to stdout and reports project ID, path, tracked/adopted counts, drift, and any snapshot IDs. --no-backup writes a warning to stderr. TUI frames use the terminal; cancellation writes to stderr.

JSON success is one stdout envelope:

schema_version: 1
kind: init
data.dir: string
data.project_id: string
data.manifest_version: integer
data.files_adopted: integer
data.files_tracked: integer
data.drifted_files: array, optional
data.snapshot: string, optional
data.claude_snapshot: string, optional
data.dry_run: boolean, optional

Execution errors in JSON mode use the structured error envelope on stderr. With --json enabled, unknown or invalid flags use the shared JSON stderr error envelope (error_code: validation_failed, exit 2). Human mode, including --json=false, prints Usage.

Exit status

Exit	Meaning	Safe next step
`0`	Initialization or explicit dry-run completed.	Review adopted paths and the manifest.
`1`	Directory, I/O, manifest, snapshot, or TTY cancellation failure.	Inspect the error and any snapshot created before retrying.
`2`	Arguments or flags were invalid.	Correct the invocation.
`6`	Tracked files drifted and `--force` was absent.	Review the named files; use `--force` only to accept their current content.

Effects, ownership, and recovery

A first run atomically creates the ownership manifest and records discovered files without changing their contents. A successful non-dry run also writes a local script-audit snapshot and attempts to add the project to the global project registry. Those two follow-up operations are best-effort: their failure does not change exit 0.

Init takes no snapshot by default. --force captures the project ownership state only, before accepting drift. --backup, or backups.enabled: true in ~/.agentkit/config.yaml, additionally captures a non-empty Claude home. --no-backup skips every init snapshot, including the one --force takes. Inspect reported IDs before recovery:

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

Snapshots cover recorded AgentKit/Claude surfaces, not the whole machine. Do not delete project or runtime homes as recovery.

ak init records ownership only. It does not authenticate, contact the kit registry, resolve entitlements, download artifacts, populate kit cache, or start external processes.

A relative --plans-dir is honored by Skill, ak plan, journals and the dashboard. An absolute value is honored only by config and Skill.