App Builder Connector Setup

This skill guides you through setting up an Adobe App Builder connector project. It offers three setup paths based on whether the user wants to set-up interactively or through agents.

Key principle: The agent acts as the interactive UI for Options 1 and 2 — running non-interactive aio sub-commands and presenting choices in chat. Option 3 hands off to a terminal script.

Connector Type → Template Mapping

When the user selects a connector type, resolve the template name from this table:

The user picks a connector type; the skill resolves the template name internally. The user never sees or types template names.

Strict Execution Order (Do Not Reorder)

Always follow this exact sequence:

1. Phase 0 (Developer Console guidance)
2. Phase 0.1 (AskQuestion: “Have you created a project already?” Yes/No)
3. Prerequisites Check
4. Authentication Preflight
5. Phase 1: Entry Question
6. Continue into Option 1/2/3

Never ask for workspace JSON before Step 4 succeeds.

AskQuestion Continuation Rule

When you use AskQuestion, wait for the answer and then continue the workflow from the matching branch in the next turn. Do not treat question prompts as terminal responses unless the branch explicitly says to exit.

Phase 0: Guide — Create Project in Developer Console

Before starting, inform the user:

Before we begin, make sure you have an App Builder project in Adobe Developer Console:

1. Go to https://developer.adobe.com/console
2. Select your organization
3. Click “Create new project” → “Project from template” → “App Builder”
4. Give it a name and save
5. In the left sidebar, open a workspace (Stage or Production)

Phase 0.1: Project Exists Gate (Required)

Use the AskQuestion tool:

Prompt: “Have you created an App Builder project already in Adobe Developer Console?”

Options:

1. Yes
2. No

Branching:

• Yes → Continue to Prerequisites Check
• No → Exit setup flow. Tell user to create the project first, then return.

Authentication Preflight (Run After Prerequisites, Before Any JSON Prompt)

Run this command after prerequisites pass:

aio auth login

Use a normal foreground run (do not background or poll).

Interpret the result:

• If command exits successfully and indicates the user is already authenticated (for example, returns an auth token / cached auth state), continue.
• If output indicates browser/device-code/manual login is required, stop immediately and do not continue to JSON flow.

If browser interaction is required, tell the user:

This setup path cannot complete Adobe login in chat-only mode. Please run the interactive onboarding script in your terminal:

npx appbuilder-connector-interactive-onboarding

After login/setup is complete there, come back and we can continue with post-setup steps.

Do not ask for workspace JSON after this failure condition.

Phase 1: Entry Question (Only After Auth Preflight Passes)

Use the AskQuestion tool:

Prompt: “Do you have the workspace config JSON downloaded from Adobe Developer Console?”

Options:

1. Yes, I’ll share the file path
2. No — how do I download it?
3. No — I want to set it up interactively

Based on the answer:

• Option 1 → Go to Option 1 (JSON Path)
• Option 2 → Go to Option 2 (Download Guide)
• Option 3 → Go to Option 3 (Interactive Script)

Prerequisites Check (Shared by All Options)

Run these commands:

node --version
npm --version
aio --version

If Node.js is missing or major version < 20:

Use AskQuestion to present options:

Node.js 20 or higher is required, but you have [version/none]. How would you like to proceed?

1. Install via nvm (recommended)
2. Install via Homebrew (macOS)
3. I’ll install it manually

Based on choice:

• Option 1 (nvm): Check if nvm exists, then:

  nvm install 20
  nvm use 20
  

  Verify with node --version, then continue.

• Option 2 (Homebrew):

  brew install node@20
  

  Verify with node --version, then continue.

• Option 3 (Manual): Tell user to download from https://nodejs.org/ and let you know when done. After confirmation, verify and continue.

If AIO CLI is missing:

Install automatically:

npm install -g @adobe/aio-cli

Verify with aio --version, then continue.

If everything is present: Run Authentication Preflight, then start Phase 1: Entry Question.

Do not start Phase 1 before preflight succeeds.

Option 1 — JSON Path (Fully Agent-Driven)

This is the fastest path. The user has already downloaded the workspace JSON from Developer Console.

Step 1.1: Ask for JSON File Path

Ask the user:

What is the path to your workspace config JSON file? (e.g. ~/Downloads/MyProject-393012-Stage.json)

The user can either:

• Provide a file path
• Paste the JSON content directly in the chat (if they shared it via @ reference, read it)

Step 1.2: Read and Confirm JSON

Read the file using the Read tool. Parse these fields:

• project.org.name → organization name
• project.name → project name
• project.workspace.name → workspace name

Confirm with the user using AskQuestion (do not use plain text only):

Prompt: “Configuring for Organization: [org], Project: [project], Workspace: [workspace]. Proceed with this workspace config?”

Options:

1. Yes, continue
2. No, I’ll provide a different JSON

Branching:

• Yes → Continue immediately to Step 1.4
• No → Return to Step 1.1 and ask for another JSON file

Step 1.3: Authentication

Authentication is already validated in Authentication Preflight.

Do not run aio auth login again here unless the user explicitly reports an auth error later in the flow.

Step 1.4: Select Connector Type

Use AskQuestion to present connector types:

What type of connector are you building?

1. Translate

When user selects, resolve the template name from the mapping table. Do not show the template name to the user.

Step 1.5: Choose Target Directory

Use ./<project-name-lowercase> as the target directory automatically. Do not use AskQuestion here — just state the directory inline and continue:

Creating project in ./<project-name-lowercase>

Create the directory if it doesn’t exist:

mkdir -p <targetDir>

Step 1.6: Pre-seed Workspace Config (CRITICAL — DO THIS FIRST)

Important: Run aio app use BEFORE aio app init. Template generators read .aio and .env during their install phase, so these files must exist first.

aio app use <jsonPath> --merge --no-input

Use working_directory: "<targetDir>".

Tell the user: “Pre-configuring workspace credentials…”

Step 1.7: Scaffold Project

Now run the init command with the resolved template:

aio app init <targetDir> --template <templateName> --yes --import <jsonPath>

• Use block_until_ms: 0 (scaffolding takes 30-60 seconds)
• Tell the user: “Scaffolding project… this may take a minute.”
• Poll the terminal file every 5 seconds until exit_code appears

After completion, verify <targetDir>/app.config.yaml exists using Glob or by listing the directory.

If scaffold failed, read terminal output to troubleshoot.

Step 1.8: Install Dependencies

npm install

Use working_directory: "<targetDir>".

Wait for completion. On failure, suggest npm cache clean --force and retry.

Step 1.9: Setup Complete — Next Steps

Tell the user:

Setup complete! Your connector project is configured at <targetDir>.

Run commands from your terminal (we do not auto-run these):

• cd <targetDir>
• aio app dev
• aio app run
• aio app deploy

Ask me if you want help troubleshooting any of these commands.

Stop here by default. Do not auto-run dev/run/deploy.

Option 2 — How to Download the JSON

The user doesn’t have the JSON yet. Guide them through downloading it, then continue with Option 1.

Step 2.1: Provide Download Instructions

Tell the user:

Here’s how to download the workspace config JSON:

1. Go to https://developer.adobe.com/console
2. Select your organization (top-right dropdown)
3. Click on your project
4. In the left sidebar, click on your workspace (e.g. Stage)
5. Click the “Download All” button (top-right of the workspace page)
6. A JSON file will be saved — e.g. MyProject-393012-Stage.json

Share the file path (or paste the contents here) when you’re ready.

Step 2.2: Wait for User Response

When the user provides the file path or content, continue with Option 1 starting at Step 1.2 (Read and Confirm JSON).

Option 3 — Interactive Script

The user wants to set everything up interactively in the terminal.

Step 3.1: Hand Off to Script

Tell the user:

Run this in your terminal:

npx appbuilder-connector-interactive-onboarding

It will walk you through:

• Adobe authentication
• Organization, project, and workspace selection
• Connector type selection
• Project scaffolding
• Dependency installation

Come back here when setup is complete if you have questions about deploying, troubleshooting, or next steps.

That’s it. The skill does not poll or wait. The user returns when they need post-setup help.

Post-Setup Commands

After setup completes (or when a user returns with an existing project), default to command guidance only.

Do not auto-run long-lived commands (aio app dev, aio app run) unless the user explicitly asks you to execute them.

For deployment, prefer giving the command first; only execute if user explicitly asks.

Start Dev Server

aio app dev

Tell user to run this in their project directory.

Run Locally

aio app run

Tell user to run this in their project directory.

Deploy

aio app deploy

Tell user to run this in their project directory.

Undeploy

aio app undeploy

View Logs

aio app logs

Configuration Management

View Current Configuration

aio console org selected
aio console project selected
aio console workspace selected

Switch Workspace

1. List available workspaces:

   aio console workspace list --json
   

2. Select the new workspace:

   aio console workspace select <workspaceId>
   

3. Download the workspace config:

   aio console workspace dl /tmp/workspace-config.json
   

4. Apply the config to the project:

   aio app use /tmp/workspace-config.json --merge --no-input
   

Switch Project

aio console project list --json
aio console project select <projectId>

Then re-select workspace as above.

Switch Organization

aio console org list --json
aio console org select <orgId>

Then re-select project and workspace.

Clear All Configs / Start Fresh

aio auth logout

Then delete local config files from the project directory:

• .aio
• .env

To start over completely, guide the user back to Phase 0.

Re-authenticate

aio auth login

If that fails, force a fresh login:

aio auth logout
aio auth login --force

Troubleshooting

Authentication Issues

Organization/Project/Workspace Issues

Template/Scaffold Issues

Deployment Issues

General Issues

Parsing Table Output

When --json flag is not supported, the aio CLI outputs tables like:

ID          Name
12345       Acme Corp
67890       Dev Sandbox

To parse:

1. Split by newlines
2. Skip the header row (first line)
3. Split each row by 2+ consecutive spaces
4. First column is ID, second is Name

Project Structure

When users ask about project structure, explain:

Workspaces isolate environments:

• Production: Live services
• Stage: Pre-production testing
• Development: Active development

Each workspace has its own Runtime namespace, credentials, and deployed actions.

Additional Resources

• App Builder Guide
• Official Documentation
• Adobe Developer Console
• I/O Runtime Documentation
• AIO CLI Reference