Skip to main content
How-to

Install and set up the StoreFront CLI

Overview​

Setup takes three steps: install the uc-storefront command, create a workspace folder for your store, and install the agent skill into that folder. None of this signs in or touches your store. Connecting a store is a separate step, covered in Connect your store.

You can run these commands yourself, or ask your agent to do it for you (see Let your agent do the setup).

Prerequisites​

  • Node.js 24 or newer, with npm. Check your version with node -v. If it is older, install Node.js 24 first, for example with a version manager such as nvm or Volta.
  • An AI coding agent that can run shell commands. See Agents it works with.
  • An UltraCart account, for when you connect a store later.

Install the CLI​

Install the CLI globally from public npm, then confirm the version:

npm install -g @ultracart/storefront-cli@beta
uc-storefront --version

The package is @ultracart/storefront-cli and the command it installs is uc-storefront. During the beta, the version starts with 0.2.

If npm cannot find the package​

Your npm configuration may send the @ultracart scope to a different registry. That happens when ~/.npmrc (or a project .npmrc) has a line such as @ultracart:registry=https://npm.pkg.github.com. npm then looks there and does not find the public package.

Add a registry override to the install command:

npm install -g @ultracart/storefront-cli@beta --@ultracart:registry=https://registry.npmjs.org/

Or remove that line from your .npmrc if you no longer need it.

Create a workspace and install the skill​

A workspace is a folder that holds one store's work: the ultracart.json project file, a recipes folder, and the agent skill. Create one with uc-storefront init, naming the agent (or agents) you use with --target:

uc-storefront init my-storefront --target claude
cd my-storefront
uc-storefront skills status
  • --target accepts claude, codex or gemini. Repeat it for more than one agent (--target codex --target claude), or use --target all.
  • In an interactive terminal you can leave out --target, and init asks which agents to set up.
  • When an agent runs init for you, its shell cannot answer prompts. Add --no-input and name the target: uc-storefront init my-storefront --target claude --no-input.

Claude Code reads the skill from .claude/skills/. Codex and Gemini CLI share .agents/skills/. init also prints which files to keep out of version control; it does not edit .gitignore for you.

Use one workspace per merchant. If you work on several stores, give each its own folder, so each folder is bound to exactly one store when you connect it.

Why the skill matters​

Installing the npm package gives you the uc-storefront command, but on its own that is not enough. The skill, build-ultracart-storefronts, is what makes your agent competent with it. It tells the agent:

  • which reference to read before each kind of change, such as checkout, item data or communications
  • how to pull a file with a baseline, preview it, and push it without overwriting newer work
  • when a change is live, when to stop and ask you, and how to relay an approval request
  • what the CLI cannot do yet, so the agent says so up front instead of improvising

An agent without the skill can still run commands, but it has none of that guidance. Always run init (or uc-storefront skills install in an existing workspace) before you ask your agent to work on a store.

Check that the skill is installed​

Run uc-storefront skills status in the workspace. It reports each installed copy of the skill, its version compared with the CLI's, and any files that are missing or were edited.

skills status confirms the files are in place. It cannot tell whether your agent has loaded them. Ask your agent to list its skills, and look for build-ultracart-storefronts. If it is missing, see The agent does not list the skill.

Let your agent do the setup​

You can paste this prompt into Claude Code, Codex or Gemini CLI, and the agent installs and sets up the toolchain for you:

Read https://www.ultracart.com/theme/assets/storefront-agent-toolchain.txt. The UltraCart StoreFront CLI is in public beta. Follow the brief to install it and set it up for me, and ask before you install anything or sign in.

The linked file is a plain-text brief written for agents. It covers the same steps as this page, plus what to do if access is refused. The agent asks before it installs anything, and you complete the sign-in yourself in your browser.

Agents it works with​

Any agent that can run shell commands can use the CLI.

AgentHow it gets the skill
Claude CodeInstalled natively by init --target claude into .claude/skills/
CodexInstalled natively by init --target codex into .agents/skills/
Gemini CLIInstalled natively by init --target gemini into .agents/skills/
Cursor, GitHub Copilot, OpenCodeRead the skill from the workspace

Start on a test store​

Start on a test storefront or an inactive theme, not your live store. Some changes, such as item content, menus and site settings, are shared by every theme and are live as soon as they are written, even when you are working on an inactive theme. Safety and human approval explains which.

If you do not have a test storefront, a second UltraCart account that you use as a developer account gives you one to work in. The REST API quickstart explains why UltraCart recommends a separate account for testing.

Keep the CLI and skill up to date​

Install the newest beta, then refresh the skill in each workspace with the same command you installed it with:

npm install -g @ultracart/storefront-cli@beta
uc-storefront --version
uc-storefront skills install
uc-storefront skills status

Add the registry override if your npm configuration needs it. Updating the CLI does not update the skill in your workspaces; skills install does. If you edited a skill file, skills install stops before changing anything, so your edits are not lost.

Next steps​

Was this page helpful?