aio-cli-plugin-commerce

commerce commands for the Adobe I/O CLI

Prerequisites
Usage
Commands
Troubleshooting

Note

There is currently a known issue affecting aio-cli so you will see a warning related to punycode. This does not impact functionality. Follow here: adobe/aio-cli#679

Prerequisites

❗ You must have Node >= 22. Consider using nvm to manage multiple versions.

❗ You must have the aio CLI installed.

❗ You must have the gh CLI tool installed and authenticated before using this plugin.

brew install gh
gh auth login

❗ The Github account used by the CLI must have permission to create repositories (write access) and install Github Applications on that repository.

Mesh Prerequisites

The prerequisites in this section are only necessary if you are provisioning API Mesh for your storefront.

❗ You must have developer access in Adobe Developer Console to create Meshes. Please make sure you have the correct entitlements and also accept the terms and conditions of the Developer Console.

❗ You must also have the api-mesh plugin installed if you wish to use mesh provisioning.

aio plugins:install @adobe/aio-cli-plugin-api-mesh

❗ You must also log in to the Adobe I/O CLI using your credentials.

# logout/clear config
aio config clear
# set cli env to "prod" or "stage"
aio config set cli.env prod
# trigger login and select your org
aio console org select

Troubleshooting

Name Restrictions

Due to AEM restrictions on subdomains the full project url cannot exceed 63 characters. You also cannot use the _ character.

⚠️ Consider using a short name, and hyphens instead of underscores.

Mesh Provisioning

If you choose a workspace with a pre-existing mesh, the mesh provisioning will fail. Create or choose an empty workspace, or delete the pre-existing mesh (only if you are sure it is unused).

Instance Selection

Sometimes your AIO authentication can become invalid. You must first aio logout and then aio login. Also verify you are using the correct cli environment (stage or prod).

Wrong Org

If you are already authenticated to experience.adobe.com with a specific org selected, the aio login command will use that authentication. If this does not match the org you are trying to use for CCM or API Mesh, you will need to log out and log in again.

404

If you see a 404 when you navigate to your storefront url, it can be due to a few reasons. Here are some steps you can take to troubleshoot:

Check the URL: Ensure that the URL you are trying to access is correct and that there are no typos. The format should be https://{branch}--{site}--{org}.aem.live
Check AEM Code Sync Bot: Ensure that the AEM Code Sync Bot is installed to the correct github repository. _you cannot select "all repositories"!

Further steps

If you are still having problems, please open an issue and confirm that you:

can consistently reproduce the issue
are able to obtain the full error output using AIO_LOG_LEVEL=debug aio commerce init.
verify you have tried using the "demo" backends
verify you have tried with and without API Mesh
verify you deleted the mesh before using the CLI (aio api-mesh:delete)
verify you have tried using unique destination repo name
verify you are in the correct IMS environment (aio config set cli.env <env>)
verify you are authorized to the correct IMS org (aio config get console.org)
Sign out of https://experience.adobe.com first before running the CLI, as this may “auto select” the wrong org
verify you are authorized to the correct gh user gh auth status

Additionally, please:

provide the storefront url
provide exact steps/inputs you chose in order to reproduce the issue

Usage

$ aio plugins:install https://github.com/adobe-commerce/aio-cli-plugin-commerce
$ # OR to install a specific tag
$ aio plugins:install https://github.com/adobe-commerce/aio-cli-plugin-commerce#semverX.Y.Z

Commands

aio commerce extensibility app-setup
aio commerce extensibility tools-setup
aio commerce init (deprecated)
aio commerce dev

`aio commerce extensibility app-setup`

USAGE
  $ aio commerce extensibility app-setup [-s <value>] [-n <value>] [-a <value>] [-p npm|yarn] [-v <value>] [-f]

FLAGS
  -s, --starter-kit=<value>      Starter kit folder (e.g. integration-starter-kit, checkout-starter-kit, aem-boilerplate-commerce)
  -n, --project-name=<value>     Name for the project directory
  -a, --agent=<value>            Coding agent to install skills for (see Supported Agents in tools-setup)
  -p, --package-manager=<option> Package manager: npm or yarn
  -v, --tools-version=<value>    Version of commerce-extensibility-tools to install (default: latest)
  -f, --force                    Force overwrite of existing MCP configuration in tools-setup

DESCRIPTION
  Setup your Commerce Extensibility app: clone starter kit, configure aio console,
  install dependencies, and run tools-setup

EXAMPLES
  $ aio commerce extensibility app-setup
  $ aio commerce extensibility app-setup --starter-kit integration-starter-kit --project-name my-app --agent Cursor
  $ aio commerce extensibility app-setup -s checkout-starter-kit -n checkout-app -a Cursor -p npm
  $ aio commerce extensibility app-setup -s aem-boilerplate-commerce -n storefront -a Cursor

This command automates the full project setup workflow for Commerce Extensibility. It runs the following steps:

Login check — verifies you are authenticated via aio auth login
Starter kit selection — prompts for Integration Starter Kit, Checkout Starter Kit, or AEM Boilerplate Commerce
Project name — prompts for a directory name for the new project
Agent selection — prompts for which coding agent to install skills for
Clone and install — clones the starter kit repo and installs dependencies
Console configuration (Integration/Checkout only) — selects Adobe I/O Console org, project, and workspace
Workspace credentials (Integration/Checkout only) — creates OAuth server-to-server credentials and subscribes to required services (ACCS REST API, I/O Management API, I/O Events, Adobe I/O Events for Adobe Commerce)
Kit-specific setup (Integration/Checkout only) — creates .env from template, configures Commerce instance, downloads workspace config, populates workspace IDs and OAuth credentials
Tools setup — runs tools-setup to install Commerce Extensibility MCP tools and agent skills

All flags are optional. When omitted, the command prompts interactively. When all flags are provided, the command runs non-interactively.

`aio commerce init`

⚠️ Deprecated: This command is deprecated. Use the Site Creator Tool instead.

USAGE
  $ aio commerce init [-d <value>] [-r <value>] [--skipGit] [--skipMesh] [-t <value>]

FLAGS
  -d, --datasource=<value>  your datasource, ie "https://my-commerce-api.com/graphql
  -r, --repo=<value>        your github repo, ie "my-git-user/my-test-storefront"
  --skipGit                 skip creating Git Repo
  --skipMesh                skip creating API Mesh
  -t, --template=<value>    the template to use, ie "hlxsites/aem-boilerplate-commerce

DESCRIPTION
  Scaffold your own Adobe Commerce on EDS storefront

EXAMPLES
  $  aio commerce:init
  $  aio commerce:init --template "hlxsites/aem-boilerplate-commerce" --skipMesh --repo "my-git-user/my-site"

`aio commerce dev`

USAGE
  $ aio commerce dev

DESCRIPTION
  one command to clone, install, and run the local development server.

EXAMPLES
  $ aio commerce:dev

`aio commerce extensibility tools-setup`

USAGE
  $ aio commerce extensibility tools-setup [-v <value>] [-s <value>] [-a <value>] [-p npm|yarn] [-f]

FLAGS
  -v, --tools-version=<value>    Version of @adobe-commerce/commerce-extensibility-tools to install (defaults to latest)
  -s, --starter-kit=<option>     Starter kit to use. e.g. "integration-starter-kit"
  -a, --agent=<value>            Coding agent to configure (see Supported Agents below)
  -p, --package-manager=<option> Package manager: "npm" or "yarn" (auto-detected from lock files if omitted)
  -f, --force                    Force overwrite of existing MCP configuration without prompting

DESCRIPTION
  Setup Commerce Extensibility Tools with Agent Skills for your coding agent

EXAMPLES
  $ aio commerce:extensibility:tools-setup
  $ aio commerce:extensibility:tools-setup --tools-version 1.2.3
  $ aio commerce:extensibility:tools-setup --starter-kit integration-starter-kit --agent Cursor --package-manager npm
  $ aio commerce:extensibility:tools-setup --starter-kit aem-boilerplate-commerce --agent Cursor --package-manager npm
  $ aio commerce:extensibility:tools-setup -s integration-starter-kit -a Cursor -p npm -f

This command sets up Commerce Extensibility Tools for use with your preferred coding agent using Agent Skills, an open standard for giving AI coding agents domain-specific expertise. The command will:

Prompt you to select a starter kit (e.g. Integration Starter Kit, Checkout Starter Kit, or AEM Boilerplate Commerce)
Prompt you to select your coding agent from 9 supported agents (plus an "Other" option)
Install the @adobe-commerce/commerce-extensibility-tools package as a dev dependency
Create MCP (Model Context Protocol) configuration for your agent
Copy AGENTS.md to your project root (top-level agent instructions)
Copy skill folders (architect, developer, tester, tutor, etc.) to your agent's skills directory
Copy examples and references folders (if provided by the starter kit) alongside the skills directory

Supported Agents

Agent	Skills Path	MCP Config
Cursor	`.cursor/skills/`	`.cursor/mcp.json`
Claude Code	`.claude/skills/`	`.mcp.json`
GitHub Copilot	`.github/skills/`	`.vscode/mcp.json`
Windsurf	`.windsurf/skills/`	Global: `~/.codeium/windsurf/mcp_config.json`
Gemini CLI	`.gemini/skills/`	`.gemini/settings.json`
OpenAI Codex	`.agents/skills/`	`.codex/config.toml`
Cline	`.cline/skills/`	Global: VS Code extension storage
Kilo Code	`.kilocode/skills/`	`.kilocode/mcp.json`
Antigravity	`.agent/skills/`	`.agent/mcp_config.json`
Other	`./skills/` (project root)	Manual setup required

Flags Reference

Flag	Short	Description
`--tools-version`	`-v`	Version of the tools package to install. Accepts semver (`1.2.3`, `^1.2.3`), ranges (`>=1.0.0`), or npm tags (`latest`, `next`). Defaults to `latest`.
`--starter-kit`	`-s`	Starter kit folder name. e.g. `integration-starter-kit`, `checkout-starter-kit`, `aem-boilerplate-commerce`.
`--agent`	`-a`	Coding agent name: `Cursor`, `Claude Code`, `GitHub Copilot`, `Windsurf`, `Gemini CLI`, `OpenAI Codex`, `Cline`, `Kilo Code`, `Antigravity`, `Other`.
`--package-manager`	`-p`	Package manager: `npm` or `yarn`. Auto-detected from lock files when omitted (see below).
`--force`	`-f`	Force overwrite of existing MCP configuration without prompting for confirmation.

All flags are optional. When a flag is omitted, the command will prompt interactively. When all flags are provided, the command runs fully non-interactively, making it suitable for CI/CD pipelines.

Package Manager Auto-Detection

When --package-manager is not provided, the command automatically detects the package manager by checking for lock files in your project directory:

yarn.lock found (no package-lock.json): uses yarn
package-lock.json found (no yarn.lock): uses npm
Both or neither found: prompts you to choose

To override auto-detection, either pass --package-manager explicitly or delete the unwanted lock file.

CI / Automation

To run the setup without any interactive prompts (e.g. in a CI pipeline), provide all flags:

aio commerce:extensibility:tools-setup \
  --starter-kit integration-starter-kit \
  --agent Cursor \
  --package-manager npm \
  --force

Navigate to your project directory before running the command. After setup, restart your coding agent to load the new MCP tools and skills.

Local Development

git clone git@github.com:adobe-commerce/aio-cli-plugin-commerce.git
cd aio-cli-plugin-commerce
npm install
aio plugins:link commerce

Templates

The requirements for adding or using a template (source site) are:

The source site github repo is a "template" repo.
The source site produces a full-index.json (see this for example).

Logging

Uses winston internally.

Use AIO_LOG_LEVEL=debug|verbose|info|warn|error <command> to see full logs.

AIO_LOG_LEVEL=debug aio commerce:extensibility:tools-setup

Contributing

Contributions are welcomed! Read the Contributing Guide for more information.

Licensing

This project is licensed under the Apache V2 License. See LICENSE for more information.

Name		Name	Last commit message	Last commit date
Latest commit History 118 Commits
.github		.github
.vscode		.vscode
bin		bin
e2e		e2e
src		src
test/commands/commerce		test/commands/commerce
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
COPYRIGHT		COPYRIGHT
LICENSE		LICENSE
README.md		README.md
jest.setup.js		jest.setup.js
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

aio-cli-plugin-commerce

Note

Prerequisites

Mesh Prerequisites

Troubleshooting

Name Restrictions

Mesh Provisioning

Instance Selection

Wrong Org

404

Further steps

Usage

Commands

`aio commerce extensibility app-setup`

`aio commerce init`

`aio commerce dev`

`aio commerce extensibility tools-setup`

Supported Agents

Flags Reference

Package Manager Auto-Detection

CI / Automation

Local Development

Templates

Logging

Contributing

Licensing

About

Uh oh!

Releases

Packages

Uh oh!

Uh oh!

Contributors 4

Languages

Folders and files

Latest commit

History

Repository files navigation

aio-cli-plugin-commerce

Note

Prerequisites

Mesh Prerequisites

Troubleshooting

Name Restrictions

Mesh Provisioning

Instance Selection

Wrong Org

404

Further steps

Usage

Commands

aio commerce extensibility app-setup

aio commerce init

aio commerce dev

aio commerce extensibility tools-setup

Supported Agents

Flags Reference

Package Manager Auto-Detection

CI / Automation

Local Development

Templates

Logging

Contributing

Licensing

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors 4

Languages

`aio commerce extensibility app-setup`

`aio commerce init`

`aio commerce dev`

`aio commerce extensibility tools-setup`

Packages