Overview

smc-upgrader upgrades an Elastic Path Self-Managed Commerce codebase to a given version.

It has the following benefits:

• Ensures the upgrade is performed via the approach recommended by Elastic Path.
• Can upgrade from and to any version of Elastic Path Self-Managed Commerce.
• Supports consuming all latest patches for your current version without performing a full version upgrade.
• Reconciles conflicts caused by the presence of Elastic Path post-release patches.
• AI Assist Mode uses a CLI-based LLM (Claude Code by default) to guide you through virtually the entire upgrade process -- from merging and conflict resolution to compilation failures, test failures, schema updates, and more.

Installation

The following section describes how to install and build smc-upgrader.

Prerequisites

To successfully install and use smc-upgrader, you will need the java command available on the PATH (Java 8 JRE or later).

Optionally, you can install ast-grep. AI Assist Mode includes an automated recipe step that applies deterministic code transformations via ast-grep before the LLM resolves compilation errors, which significantly reduces the number of issues the LLM needs to address. Installation instructions are included in the Homebrew and binary installation sections below.

ast-grep is not required. If it is not installed on your PATH, the recipe step does not fail the upgrade: it logs a warning, skips the automated transformations, and leaves the step in progress. You can either install ast-grep and re-run smc-upgrader --ai:continue to apply the recipes, or skip the step entirely by marking it complete ([M]) at the prompt. Skipping simply means the LLM resolves more compilation issues manually instead of having them fixed deterministically up front.

Homebrew installation

1. Tap the smc-upgrader's formula repository:

   brew tap elasticpath/smc-upgrader
   

2. Install smc-upgrader:

   brew install smc-upgrader
   

3. Validate the installation by checking the version:

   smc-upgrader --help
   

4. Optional: install ast-grep for AI Assist Mode (see Prerequisites):

   brew install ast-grep
   

Binary Installation

1. Go to smc-upgrader releases and check for currently available releases.

2. Download the required zip file and place it into a folder, such as ~/tools/smc-upgrader.

3. Extract the downloaded file:

   unzip smc-upgrader-2.0.0.zip
   

4. Set up alias/shortcut:

   1. On a *nix running bash, including Mac, create an alias in your terminal.

   Note: This can also be made for permanent use, by adding it to your ~/.bash_profile.

   alias smc-upgrader='java -jar ~/tools/smc-upgrader/smc-upgrader-2.0.0-jar-with-dependencies.jar'
   

   1. On Windows you will likely want to create a smc-upgrader.cmd file on your PATH that looks like this:

   @echo off
   set SMC_UPGRADER_JAR=C:\path\to\smc-upgrader\smc-upgrader-2.0.0-jar-with-dependencies.jar
   java -jar "%SMC_UPGRADER_JAR%" %*
   

5. Execute smc-upgrader --help to verify the installation.

6. Optional: install ast-grep for AI Assist Mode (see Prerequisites). You can install it using either npm or pip:

   npm install --global @ast-grep/cli
   

   pip install ast-grep-cli
   

Build from source

1. Clone and build the project source as shown in the following example:

   cd ~/git
   git clone git@github.com:elasticpath/smc-upgrader.git
   cd smc-upgrader
   ./smc-upgraderw clean install
   

2. Set up alias/shortcut:

   1. On a *nix running bash, including Mac, create an alias in your terminal.

   Note: This can also be made for permanent use, by adding it to your ~/.bash_profile.

   alias smc-upgrader='java -jar ~/git/smc-upgrader/target/smc-upgrader-2.0.0-SNAPSHOT-jar-with-dependencies.jar'
   

   2. On Windows you will likely want to create a smc-upgrader.cmd file on your PATH that looks like this:

   @echo off
   set SMC_UPGRADER_JAR=C:\path\to\git\smc-upgrader\target\smc-upgrader-2.0.0-SNAPSHOT-jar-with-dependencies.jar
   java -jar "%SMC_UPGRADER_JAR%" %*
   

3. Execute smc-upgrader --help to verify the installation.

Connecting to code.elasticpath.com

smc-upgrader fetches upgrade commits from the Elastic Path Self-Managed Commerce repository at code.elasticpath.com. Before you can use the tool in either Standard Mode or AI Assist Mode, you need to set up authenticated access to that repository over SSH or HTTPS.

Complete these steps once per machine. The first smc-upgrader run will fail at the fetch step if any of them is skipped.

1. Verify browser access

Open https://code.elasticpath.com/ep-commerce/ep-commerce and log in.

If you do not have credentials, or your account cannot access the repository, contact Elastic Path Customer Support (access@elasticpath.com) to request access before continuing.

2. Generate an SSH key pair

Generate an SSH key pair (skip this step if you already have one you want to reuse):

ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa_smc

3. Add the public key to your GitLab account

Copy the contents of ~/.ssh/id_rsa_smc.pub and add it as a new SSH key on your code.elasticpath.com account at https://code.elasticpath.com/-/user_settings/ssh_keys.

4. Configure SSH to use the key for code.elasticpath.com

Add the following block to your SSH config file so that this key is used whenever connecting to code.elasticpath.com:

Host code.elasticpath.com
    IdentityFile ~/.ssh/id_rsa_smc
    IdentitiesOnly yes

The SSH config file is at ~/.ssh/config on macOS and Linux, and at %USERPROFILE%\.ssh\config on Windows. Create the file if it does not exist.

5. Add the Git remote

In your codebase, add code.elasticpath.com as a remote called smc-upgrades:

git remote add smc-upgrades git@code.elasticpath.com:ep-commerce/ep-commerce.git

If your network blocks SSH access to code.elasticpath.com, use HTTPS instead:

git remote add smc-upgrades https://code.elasticpath.com/ep-commerce/ep-commerce.git

6. Verify the connection

Run the following command to confirm that authentication and access are working:

git ls-remote smc-upgrades

If this prints a list of branches and tags, setup is complete. If it fails, see Troubleshooting.

Command Line Options

Usage: smc-upgrader [-dfhmprvV] [--ai:continue] [--ai:skip-permissions] [--ai:
                    start] [--[no-]clean-working-directory-check]
                    [-C=<workingDir>] [<version>]
Utility to apply Elastic Path Self-Managed Commerce updates to a codebase.
      [<version>]            The version of Elastic Path Self-Managed Commerce
                               to upgrade to. Optional when using --ai:start or
                               --ai:continue.
      --ai:continue          Continue AI-assisted upgrade from saved plan.
      --ai:skip-permissions  Skip permission prompts when invoking the
                               configured CLI LLM (passes the skip-permissions
                               argument, by default
                               --dangerously-skip-permissions for Claude Code;
                               configurable in ~/.smc-upgrader.json).
      --ai:start             Start AI-assisted upgrade mode and generate
                               upgrade plan. Requires version parameter.
  -C=<workingDir>            The working directory containing the git repo to
                               be upgraded. Defaults to the current working
                               directory.
      --[no-]clean-working-directory-check
                             Indicates whether to do a clean working directory
                               check. Enabled by default.
  -d, --[no-]resolve-diffs   Indicates whether to reconcile diffs between the
                               merged branch and the upstream contents. Enabled
                               by default.
  -f, --[no-]fetch           Indicates whether to fetch the latest updates from
                               the remote. Enabled by default.
  -h, --help                 Show this help message and exit.
  -m, --[no-]merge           Indicates whether to perform a merge. Enabled by
                               default.
  -p, --[no-]revert-patches  Indicates whether to revert patches before
                               merging. Enabled by default.
  -r, --[no-]resolve-conflicts
                             Indicates whether to resolve merge conflicts.
                               Enabled by default.
  -v, --verbose              Enables debug logging.
  -V, --version              Print version information and exit.

Standard Mode Usage

The following sections describe how to use smc-upgrader in standard mode (without the --ai flags).

Setup

If you have not already done so, follow Connecting to code.elasticpath.com to set up SSH access and add the smc-upgrades Git remote.

Upgrading

The primary usage for smc-upgrader is to upgrade an existing codebase to a specified release version by executing these steps:

1. Fetch step: Fetches the latest updates from the release/<version> branch of the code.elasticpath.com repository.
2. Merge step: Merges the release/<version> branch of the code.elasticpath.com repository into the current branch.
3. Resolve conflicts step: Iterates across each file with conflicts, checking to see if the file contents of the latest commit matches a commit in a code.elasticpath.com branch. If it does, resolves the conflict using the code.elasticpath.com version of the file.
4. Resolve diffs step: Iterates across each file in the repo, checking to see if the file contents of the latest commit matches a commit in a code.elasticpath.com branch. If it does, overwrites the file contents with the code.elasticpath.com file contents.

This can be started by running:

smc-upgrader 8.5.x

Once you have finished resolving all conflicts, you can complete the merge by running:

git merge --continue

Alternately, you can cancel the merge with:

git merge --abort

If you prefer to start the merge manually, and then only have smc-upgrader attempt to resolve conflicts automatically, use this command:

smc-upgrader --no-merge 8.5.x

Demonstration

AI Assist Mode Usage

The following sections describe how to use smc-upgrader in AI assist mode (with the --ai flags).

Important: AI Assist Mode is not a fully automated process. Experienced developers must actively guide the LLM throughout the upgrade and carefully review all changes it makes. LLMs can make mistakes -- for example, it may replace important customer customizations with standard platform functionality rather than correctly merging the two. Do not treat any AI-generated change as correct without review.

AI Assist Mode works best when the codebase has extensive automated regression tests that cover all custom functionality. These tests are the primary mechanism for detecting mistakes. If comprehensive test coverage is not present, AI Assist Mode may not be able to complete the upgrade successfully, and manual review effort will increase significantly.

Note on usage fees: For most LLM CLI tools, usage is billed based on the number of tokens processed. Upgrading a large codebase may result in significant billing charges.

Setup

If you have not already done so, follow Connecting to code.elasticpath.com to set up SSH access and add the smc-upgrades Git remote.

Requirement: AI Assist Mode requires a CLI-based LLM. By default it uses Claude Code, which requires a paid Claude plan. Install Claude Code and sign up for a paid plan before proceeding, or configure a different CLI LLM as described in Configuring the CLI LLM.

Configuring the CLI LLM

By default, AI Assist Mode invokes Claude Code as:

claude --model sonnet '<prompt>'

When --ai:skip-permissions is used, --dangerously-skip-permissions is added before --model.

You can drive a different CLI-based LLM, or change how Claude Code is invoked, by creating a machine-wide configuration file at ~/.smc-upgrader.json. This file is shared by all project folders. When the file is absent, or any field is omitted, the defaults reproduce the behavior above exactly.

{
  "llm": {
    "command": "{executable} {permissions} --model sonnet {prompt}",
    "executable": "claude",
    "skipPermissionsArg": "--dangerously-skip-permissions"
  }
}

The command is an invocation template with three placeholders:

• {executable} is replaced with the executable value. The executable is also the target of the availability check that runs before invocation, so the binary name is defined in one place. If you omit the {executable} placeholder from command, the availability check uses the first whitespace-delimited token of the command instead.
• {permissions} is replaced with skipPermissionsArg when --ai:skip-permissions is active, and removed otherwise.
• {prompt} is replaced with the prompt. This placeholder is required; if command omits it, the tool reports an error at startup. The tool single-quotes and shell-escapes the prompt for you, so do not add quotes around {prompt} in your template.

The model is configured inline within command, since model identifiers are tool-specific.

If the configured executable is not found on the PATH, the step fails with a clear error rather than proceeding.

For example, to drive GitHub Copilot CLI:

{
  "llm": {
    "command": "{executable} {permissions} --prompt {prompt}",
    "executable": "copilot",
    "skipPermissionsArg": "--allow-all"
  }
}

With --ai:skip-permissions, this runs copilot --allow-all --prompt '<prompt>'.

Note: The plan step prompts are authored and tuned for Claude Code. If you configure a different CLI LLM, the default prompts may not yield effective or optimal results, so you will likely need to customize the plan steps after generation. See AI Assist Start for how to review and edit the generated smc-upgrader-plan.md.

AI Assist Start

AI Assist Mode can be used to help with version upgrades or to consume all the latest patches for your current version. The tool generates a plan containing all required steps, which are executed one at a time. Steps cover the full upgrade workflow, including:

• Merging the upgraded platform codebase into your branch
• Resolving Git merge conflicts
• Fixing Maven validation and compilation failures
• Resolving unit test and integration test failures
• Handling schema update issues
• Resolving Cucumber test failures
• Fixing server startup problems

To start an AI-assisted upgrade, run:

smc-upgrader --ai:start <version>

Where <version> is the target version you want to upgrade to, such as 8.7.x.

To consume all latest patches on your current version without performing a full version upgrade, pass your current version instead:

smc-upgrader --ai:start <current-version>

This step will generate an upgrade plan file named smc-upgrader-plan.md and commit it to Git with a commit message starting with Generated upgrade plan.

We recommend that you review the upgrade plan before continuing. You can add or remove steps, change prompts, or make any other required changes to the plan, which will be read by the tool for all subsequent operations.

The step prompts are authored and tuned for Claude Code. If you have configured a different CLI LLM (see Configuring the CLI LLM), expect to customize these prompts for effective or optimal results.

AI Assist Continue

Once you are ready to continue, run:

smc-upgrader --ai:continue

The tool will read the upgrade plan from smc-upgrader-plan.md and check to see if there are any steps in the in progress state. If it finds one, it will prompt the user to decide what they want to do next, as in the following example:

INFO : Next step: Resolve all unit test failures
INFO :   Tool: llm
INFO :   Validation command: mvn clean install -DskipITests -DskipCucumberTests -T0.75C
INFO :
INFO : What would you like to do?
INFO :   [E] Execute this step
INFO :   [V] Verify that this step is complete
INFO :   [M] Mark this step as complete
INFO :   [X] Exit

If you choose E, then the LLM will be executed again with the prompt specified in the plan. If you choose V, then the validation command will be executed (this may take a few minutes), and if successful, the step will be marked as complete, and the tool will exit. If you choose M, the step will be marked as complete, and the tool will exit. If you choose X, the tool will just exit without doing anything else.

If there are no steps in progress, the tool will find the first not started step, change it to in progress, and execute the step automatically.

By default, the first step is to start merging from the Self-Managed Commerce repository. This step will be completed automatically and does not involve AI. For all other steps, the LLM CLI will be invoked with the prompt from the plan.

Note: If your LLM CLI is Claude Code, you can interact with Claude Code normally, providing guidance or correcting mistakes. Claude Code may also ask for advice when it's not sure about the best way to proceed. When Claude Code appears to be done, type /exit to exit the interactive Claude Code tool.

When the LLM CLI exits, you will be prompted to decide what you want to do:

INFO : The LLM CLI completed successfully.
INFO :
INFO : Was this step successfully completed?
INFO :   [Y/M] Mark this step as complete
INFO :   [V] Verify that this step is complete
INFO :   [N/X] Exit
INFO :

If you choose Y or M, the step will be marked as complete, and the tool will exit. If you choose V, then the validation command will be executed (this may take a few minutes), and if successful, the step will be marked as complete, and the tool will exit. If you choose N or X, the tool will just exit without doing anything else.

You can then run smc-upgrader --ai:continue again to continue the current step or move on to the next step. Keep running this command until all steps are completed.

Troubleshooting

Git merge failed. Usually this means that Git could not find a common ancestor commit between your branch and the Self Managed Commerce release branch.

If smc-upgrader shows this error, it usually means that your Git repository was initialized using a snapshot of the source code, rather than by cloning from code.elasticpath.com. This will be the case if your project team started with SMC 7.0.1 or earlier, before the code.elasticpath.com public repository was available.

Follow these steps to create a common ancestor in your Git repository:

1. Browse to the code.elasticpath.com repository and make note of the SHA of the commit representing your current version of Self-Managed Commerce. For example, the SHA for SMC 8.5 is 08d434d4b7bc577c0b15f3b600dba4e6dc4a63fd.
2. Ensure that you have followed the Connecting to code.elasticpath.com steps and have a terminal window open in your source code folder.
3. Create a temporary branch containing the code.elasticpath.com release source code. Replace ${SHA} with the SHA that you identified in step 1.

git checkout -b temp-branch ${SHA}

4. Switch back to your main or develop branch:

git checkout main

5. Create a feature branch for the upgrade:

git checkout -b smc-upgrade

6. Merge from the temp-branch, but throw away all the changes:

git merge --allow-unrelated-histories -s ours temp-branch

7. Delete the temp-branch:

git branch -D temp-branch

8. Follow the upgrading steps normally.

You should only have to do this once; future uses of the tool should work without issue.

SSH authentication fails with "No keys found in identity" or "Cannot log in"

This usually means one of the prerequisites in Connecting to code.elasticpath.com is missing or misconfigured. Common causes:

• The public key has not been added to your code.elasticpath.com GitLab account.
• ~/.ssh/config does not bind the configured key to Host code.elasticpath.com, so SSH is offering a different key.
• Your account does not have access to the ep-commerce/ep-commerce repository. Confirm by opening https://code.elasticpath.com/ep-commerce/ep-commerce in a browser; if you cannot access it there, contact Elastic Path Customer Support.