ak onboard

Complete first-run setup, AgentKit login, and Kit installation through one state-aware conductor.

Use ak onboard for the first AgentKit setup on a workstation or in a project. It checks setup, CLI authentication, and the selected Kit route, then runs only the missing steps.

Usage

ak onboard [flags]

The command accepts no positional arguments and has no aliases.

Interactive onboarding needs terminal input and output when it must configure preferences or create a login session. Every directory except the user home is valid project scope, including an empty directory with no .git or ownership manifest. Select user scope with --global.

ak onboard
ak onboard --kit engineer --target codex --channel <channel>
ak onboard --global --yes

AgentKit login and runtime-provider login are separate. Onboard can create the AgentKit CLI session, but it does not sign Claude Code, Codex, Cursor, Grok, Pi, or Oh My Pi in to their providers.

Options

Flag	Default	Description
`--channel <channel>`	Published channel, persisted preference, or version inference	Persist and use `stable` or `beta` for both Kit downloads and binary updates.
`--email <address>`	Empty	Use this email for TTY OTP login when no CLI session exists.
`-g, --global`	`false`	Install the Kit at user scope instead of project scope.
`--kit <name>`	`kit.default`, otherwise `engineer`	Select the Kit to install.
`--project-dir <path>`	Current directory	Select the project directory; the user home requires `--global`.
`--target <runtime>`	First enabled adapter	Select the runtime target. It is required in non-interactive mode when no adapter is configured.

Shared flags such as --json, --no-interactive, --quiet, and --yes are described in CLI conventions.

State-aware execution

Onboard evaluates these stages in order:

Run basic setup only when adapters.enabled or kit.default is missing.
Resolve and persist both updates.channel and kit.channel.
Resolve project or global scope before login.
Prompt for email OTP or a user API key only when no renewable CLI session exists.
Resolve the Kit and target, then install only when the selected route has no install receipt.

An existing stage is returned as skipped; a completed stage is not replayed just because a later stage is missing. If installation reports an authentication failure during interactive use, onboard can log in and retry the installation once.

First installation is preserve-only. --yes accepts confirmation prompts but never enables force, replacement, or ownership takeover.

Scope and channel resolution

Invocation location	Behavior
Any directory except the user home	Treats that directory as project scope and installs the Kit there.
User home on a TTY	Runs missing setup, warns that home is not project scope, then offers global install or cancellation. Cancellation exits `3`.
User home without a TTY	Exits `2` before login and suggests changing directories or using `--global`.
`--global`	Skips project validation and installs user-wide, including from the user home.
`--project-dir <path>`	Replaces the current directory; the user home remains blocked unless `--global` is also present.

Channel selection prioritizes an explicit --channel stable|beta, a published -beta CLI, a persisted kit.channel, then version inference. Beta binaries resolve beta; development and Stable binaries resolve stable. Unsupported explicit values exit 2 without changing config.

Kit selection uses --kit, then kit.default, then engineer; a configured default of none also resolves to engineer. Target selection uses --target, then the first enabled adapter, then a TTY prompt. Without a TTY, a missing target exits 2.

Email OTP is the default TTY login method. --email <address> skips the method picker and goes directly to OTP. An authentication failure during interactive installation triggers login and exactly one retry.

Non-interactive behavior

--json, --quiet, non-terminal output, or explicit --no-interactive selects the scripted path. Scripted onboarding can fill basic configuration, using --kit or engineer, --target or claude-code, and telemetry disabled. It cannot collect a new credential. Create a CLI session first:

ak login --api-key ak_live_... --no-interactive
ak onboard --no-interactive --yes --project-dir /path/to/project \
  --kit engineer --target codex --channel <channel>

Missing session, target, or valid project scope exits 2 rather than opening a prompt.

Output and exit status

Human and JSON success output report setup, login, and kit as ran or skipped, plus a next action. The JSON result uses the standard kind=onboard envelope. Diagnostics and structured command errors use stderr.

Exit	Meaning	Safe next step
`0`	Every required stage is known-good for this invocation.	Restart the runtime and invoke an installed Skill.
`1`	Setup, authentication, runtime resolution, or Kit installation failed.	Read the reported stage and correct that layer before rerunning; a TTY may offer to open a GitHub issue.
`2`	The invocation is incomplete or invalid, including missing non-interactive state.	Add the required session, target, project, or supported channel.
`3`	The user cancelled the terminal wizard.	Rerun when ready; do not assume later stages completed.

Effects and verification

Depending on missing state, onboard may update ~/.agentkit/config.yaml, save a restricted CLI session, and write project- or user-scoped Kit files. It does not adopt the repository as an AgentKit-owned project; use ak init for that separate operation.

After success, run ak whoami, ak licenses, and ak doctor --exit-on-fail, then reopen the runtime and invoke one installed Skill.