/appbuilder-project-init

name: appbuilder-project-init
description: Initialize an Adobe App Builder project end-to-end and prepare the machine to build one. Creates the Console project and workspace, subscribes APIs (including those needing a product profile), maps intent to the right template, runs non-interactive `aio app init`, and guides post-init customization. Use whenever the user mentions creating an App Builder app, scaffolding a project, `aio app init`, an Experience Cloud extension, adding actions or web assets, or creating a Console project/workspace — even without saying "App Builder". Also for SPA templates, AEM extensions, API Mesh, Asset Compute workers, and MCP servers. Also covers first-time machine/CLI setup (Node 20, aio CLI install, `aio login`, IMS org, stage vs prod) and debugging setup/init failures — `ERR_REQUIRE_ESM`, empty `aio console org list`, `451 accept developer terms`, template not found, init hangs, or Node/npm and post-init build errors.
metadata:
  category: project-initialization
license: Apache-2.0
compatibility: Requires aio CLI (Adobe I/O CLI) — install or refresh with `npm install -g @adobe/aio-cli` so the bundled plugins (`aio-cli-plugin-console`, `aio-cli-plugin-app`, etc.) are current. Node.js 18+ (Node 24 supported on Stage runtimes). Bash shell.
allowed-tools: Bash(aio:*) Bash(npm:*) Bash(node:*) Read Write

App Builder Project Initialization

Maps user intent to the right Adobe App Builder template and runs non-interactive `aio app init`. Default: `@adobe/generator-app-excshell` (SPA + actions). For headless/bare projects, use `init-bare`.

When a Developer Console project / workspace / API subscription does not yet exist, this skill walks the agent through creating them non-interactively by calling `aio console …` directly — see the **Bootstrap** section and [references/bootstrap.md](references/bootstrap.md). The latest `@adobe/aio-cli` bundle exposes non-interactive `aio console project create` / `workspace create` / `api list` / `workspace api add` (with `--license-config` for services that require a product profile), and non-interactive `aio app init --org/--project/--template-options`. Together they remove every blocking "open the Developer Console UI and click" step from the agentic setup path. Just install the latest CLI (`npm install -g @adobe/aio-cli`) and use them.

Machine setup (first time)

Do this once per machine before initializing a project — plus a login per environment. If the CLI is already installed and you're logged in, skip to **Bootstrap** below.

1. Node 20

App Builder needs **Node 20** (npm ships with it). Check what's active: `node -v` → expect `v20.x`.

• **Have nvm?** `nvm install 20 && nvm use 20 && nvm alias default 20` so new shells keep it. If several Node versions are installed, the *active* one must be 20.
• **No Node / no nvm?** Install nvm, then Node 20:

  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
  # reopen the shell, then:
  nvm install 20 && nvm use 20 && nvm alias default 20

(Alternatives: `brew install node@20`, or the official installer at nodejs.org.)

> Older Adobe docs say Node 18 — use **20**. A global `aio` belongs to whichever Node was active when you ran `npm i -g`; if you switch Node versions the old `aio` won't be on PATH. Symptom of a mismatch: `aio` dies with `SyntaxError: Unexpected token '??='` (a pre-20 Node parsing the Node-20 `aio`) — fix with `nvm use 20` and reinstall `aio` there.

2. Install the aio CLI + log in

npm install -g @adobe/aio-cli      # on Node 20
aio login                          # opens a browser; `aio login -f` forces a fresh prompt
aio where                          # confirm the correct IMS org/context
aio console org list               # list orgs and their IDs (then `aio console org select <id>` if needed)

Tokens are stored by the CLI automatically; a normal `aio login` lasts hours/days — one login per session, not per command. Confirm the **correct IMS org** — wrong-org is the most common setup mistake.

3. Stage vs prod

The default environment is **prod**. To target **stage**, set the env var and re-authenticate:

export AIO_CLI_ENV=stage
aio logout && aio login

Unset the variable (or open a new shell) to return to prod. The stage CLI talks to the stage Console (`developer-stage`).

Logging in without a browser (CI / no human)

• **Import creds:** in the Developer Console open the workspace → **Download all** → `console.json`, then `aio app init <app> --import path/to/console.json` (fills `.env`/`.aio` — treat `console.json` as a secret, gitignore it).
• **CI / pipeline:** add an **OAuth Server-to-Server** credential to the workspace; `aio` and Runtime authenticate from the client id/secret with no human. Don't script SSO/MFA headlessly.

Bootstrap the Developer Console (project, workspace, APIs)

If the user is starting from zero — no Developer Console project yet, or an existing project that is missing a workspace or API subscription — bootstrap that state **before** `aio app init`. Otherwise `aio app init` / `aio app use` / `aio app deploy` have nothing to wire the local app to.

The full bootstrap is just `aio` commands; **call them directly**, not through a wrapper script. They are already non-interactive in the recent plugin releases, and per-step calls let you react to "already exists" or "needs a product profile" responses without baking those decisions into bash.

Preflight

Make sure the CLI is current — that's what brings in the non-interactive Console + app init commands:

npm install -g @adobe/aio-cli
aio --version

Don't try to assert specific plugin versions; just take the latest. If a `console` or `app` subcommand below is rejected as "command not found" or "unknown flag" after this, the CLI install genuinely failed (PATH issue, permissions, registry mirror) — fix the install rather than working around it.

Confirm an org is selected (or