Appbuilder Project Init

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. 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 pass --orgId on every command below):

aio console org list --json   # if needed, then:
aio console org select <orgId>

Decision rule

Always check what already exists with aio console project list --json and aio console workspace api list --projectName <p> --workspaceName <w> --json before creating — these commands fail loudly on "already exists" and there is no built-in idempotency.

The bootstrap chain (raw commands)

Step 1 — create the Console project:

aio console project create -n my-project --json
# optional: -t "Title" -d "Description" -o <orgId>

Step 2 — create a workspace inside it (Stage is the conventional first non-Production workspace; pick a more descriptive name in long-lived shared projects):

aio console workspace create \
  --projectName my-project \
  --name Stage \
  --json
# optional: --orgId <orgId> --title "Stage workspace"

Step 3 — discover and subscribe the APIs the app needs:

aio console api list --json   # see all service codes available to the org
                              # entries flagged for whether they need a product profile

# Free-tier service:
aio console workspace api add \
  --projectName my-project \
  --workspaceName Stage \
  --service-code AdobeIOManagementAPISDK \
  --json

# Service that requires a product profile:
aio console workspace api add \
  --projectName my-project \
  --workspaceName Stage \
  --service-code AdobeAnalyticsSDK \
  --license-config AdobeAnalyticsSDK=AnalyticsProductionProfile \
  --json

--service-code accepts a comma-separated list to subscribe several free-tier services in one call. --license-config is repeatable when several profile-bound services are added together.

Recover from per-step failures

Wire the local app to the bootstrapped state

Two equivalent ways to point a fresh aio app init at the project/workspace you just created:

1. Pass them as flags to init itself (cleanest):

   skills/appbuilder-project-init/scripts/init.sh init \
     "@adobe/generator-app-excshell" ./my-project \
     --org <orgId> --project my-project

   The wrapper passes --org / --project / --template-options straight through to aio app init, on top of the existing -y --no-login --no-install flags.

2. Run aio app use after init (works on any plugin version):

   cd ./my-project
   aio app use --no-input   # adopts the currently selected project/workspace, no prompts

Either route ends with the local .aio and .env pointing at the workspace you just bootstrapped, so aio app deploy publishes to the right namespace.

Fast Path (for clear requests)

When the user's intent maps unambiguously to a single template — for example, they name a template directly or describe an app that clearly matches exactly one entry below — skip straight to Initialize via Script below. Use the matched template and any project name the user provided (or a sensible default).

Examples of fast-path triggers:

• "Create an App Builder app using @adobe/generator-app-excshell" → use that template, run init
• "Set up an Asset Compute worker" → maps unambiguously to @adobe/generator-app-asset-compute, run init
• "Create a new App Builder app" (no specifics) → defaults to @adobe/generator-app-excshell, run init
• "Initialize a bare project" → use init-bare, run init

If there is any ambiguity — multiple templates could fit, or the user's constraints are unclear — use the full template decision table and workflow below.

Template Decision Table

Pick the template that matches the user's intent. When unclear, default to @adobe/generator-app-excshell.

For a headless/backend-only request, prefer init-bare when possible. If the user still needs a template that generates UI files, plan a post-init cleanup so the final project has no web-src frontend directory or web manifest wiring.

Initialize via Script

The aio app * wrappers go through a single script: scripts/init.sh. (Console bootstrap commands are called directly — see the Bootstrap section above for the rationale.)

Note: The path to this skill's scripts may be skills/, .augment/skills/, or .github/skills/ depending on your platform and repository layout. Adjust the prefix in the commands below accordingly.

With a template:

skills/appbuilder-project-init/scripts/init.sh init "@adobe/generator-app-excshell" ./my-project

With a template, fully wired to a specific Console org/project (no post-init aio app use needed):

skills/appbuilder-project-init/scripts/init.sh init \
  "@adobe/generator-app-excshell" ./my-project \
  --org <orgId> --project my-project

--org, --project, --template-options (base64-encoded JSON), and --no-config-validation are passed straight through to aio app init. Use the latest @adobe/aio-cli so they're all recognised; --no-config-validation is the escape hatch for the rare case where a partial scaffold shouldn't yet have to pass schema validation.

Bare project (no template):

skills/appbuilder-project-init/scripts/init.sh init-bare ./my-project

Use init-bare only when the user explicitly wants to configure everything from scratch. In that case, "bare" means the generated project should stay minimal:

• app.config.yaml exists with an empty or minimal application.runtimeManifest
• package.json exists with only the basic project dependencies
• No pre-scaffolded src/, web-src/, or actions/ directories

Why this matters: if the user asked for a bare project, pre-generated actions or web assets contradict that intent and remove the clean starting point they requested.

The script outputs JSON with success, path, and output fields. Check success before proceeding.

Full Workflow (for ambiguous or complex requests)

Step 1 — Gather intent

Ask the user (or infer from conversation context):

If the user simply says "create an App Builder app" with no specifics, default to @adobe/generator-app-excshell.

If the Console state is "from scratch" or unknown, run the Bootstrap the Developer Console flow before continuing to template selection. See references/bootstrap.md for the full agentic bootstrap playbook.

Step 2 — Select template

Consult the Template Decision Table above and references/templates.md to map the user's intent to a template.

Step 3 — Initialize, customize, validate

Follow the Initialize via Script, Post-init customization, and Validate sections below.