Upstorr CLI

The Upstorr CLI creates, previews, checks and uploads custom retail themes that run on Upstorr's commerce backend.

It is Developer Mode, the third layer of Upstorr Design Control: Founder Mode uses visual controls, Agency Mode edits one Liquid section at a time, and Developer Mode opens the complete authored theme. Read docs/upstorr-design-control.md in the installed CLI package, or open Upstorr Design Control online.

Requirements

  • Node.js 20.9 or newer
  • A merchant development secret for the store you are allowed to work on

Start a theme

npm install --global @upstorr/cli
mkdir my-upstorr-themes
cd my-upstorr-themes
upstorr theme init "My Brand Theme"
upstorr theme connect my-brand-theme
upstorr theme dev my-brand-theme

Paste the merchant development secret only when the CLI asks for it. This keeps the secret out of shell history.

The command creates themes/my-brand-theme/. Edit only its theme/ folder. .upstorr-theme/ is generated local state. The generated checkout also contains README.md, a docs/ folder and SDK type information, so an agency can understand the structure and get editor autocomplete without cloning the Upstorr monorepo.

Main commands

upstorr theme check my-brand-theme
upstorr theme dev my-brand-theme
upstorr theme upload-version my-brand-theme

check validates the folder boundary, Liquid sources, required retail templates, imports and unsafe platform access. dev opens the connected Workbench. upload-version creates an unpublished version; it does not publish the theme to production.

Custom JavaScript and libraries

Put optional browser JavaScript in theme/assets/theme.ts. The CLI bundles and loads it in local preview and uploaded versions. To run an enhancement again after storefront navigation:

const enhance = () => {
  // Find the new page elements and attach your theme-only interactions.
};

enhance();
window.addEventListener('upstorr:storefront-navigation', enhance);

Install normal browser libraries in the theme checkout and declare them in its root package.json. Private @upstorr/* packages, Node/server modules, direct API requests, authentication and payment-provider code are blocked. Use @upstorr/theme-sdk/v1 and documented Liquid behaviour hooks for platform data and commerce actions.

For the full folder map, Liquid rules and SDK contract, open the docs/ folder generated beside your theme.

The same documentation is available online at help.upstorr.com/developers.