Upstorr CLI command reference

The CLI manages custom retail themes. Run commands from an Upstorr theme workspace. A workspace contains upstorr-workspace.json and stores each theme inside themes/.

upstorr theme init

Create a theme from Upstorr's basic bespoke starter:

upstorr theme init "My Brand Theme"

The CLI creates themes/my-brand-theme/, installs SDK autocomplete, copies these developer guides and prepares local Workbench state. The destination must be empty. Use a different workspace directory with:

upstorr theme init "My Brand Theme" --workspace ./my-themes

There is currently one starter, so there is no starter-selection option.

upstorr theme connect

Connect a local theme to a store:

upstorr theme connect my-brand-theme

Paste the merchant development secret when prompted. Prompting keeps the secret out of terminal history. A theme may only connect when the secret permits its theme key. Upstorr saves connection details under .upstorr-theme/; do not commit or edit them.

For automated local testing, --token <secret> is supported, but the prompt is safer for normal use.

upstorr theme dev

Check the theme, start its local preview server and open the hosted Workbench:

upstorr theme dev my-brand-theme

The default local address uses 127.0.0.1 and port 3210. Optional local-development flags are:

upstorr theme dev my-brand-theme --host 127.0.0.1 --port 3211 --no-open

--no-open prints the Workbench URL without opening a browser. Keep this command running while using the preview. Upstorr manages the API and Workbench origins; custom origin flags are intentionally rejected.

upstorr theme check

Validate the authored theme before upload:

upstorr theme check my-brand-theme

The check validates the allowed folder boundary, required retail templates, JSON and Liquid syntax, schema references, browser imports and prohibited private platform access. It writes the latest result to .upstorr-theme/check-result.json.

Fix every reported error before uploading. A passing check proves the package follows the theme contract; it does not replace visual and checkout testing.

upstorr theme upload-version

Compile and upload an unpublished theme version:

upstorr theme upload-version my-brand-theme

The command checks the theme first. It uploads only allowed authored files plus generated, integrity-checked artifacts. It never publishes a storefront by itself.

If the store has not installed this custom theme before, Upstorr creates a new draft theme. Otherwise, Admin shows the uploaded version as an available update for the existing theme. The merchant reviews the draft or update and chooses when to publish it.

Running the exact same upload safely reuses the same operation identity instead of producing an accidental duplicate operation.

upstorr theme rename

Rename the theme's display name, folder key and local metadata together:

upstorr theme rename my-brand-theme "My New Theme Name"

The new name must not collide with another theme in the workspace. Renaming updates local identity and connection records; it does not silently rename an already installed merchant theme.

upstorr theme disconnect

Stop using the active store connection for a theme:

upstorr theme disconnect my-brand-theme

The previous connection record is kept locally for deliberate reuse, but it is no longer active. Disconnecting does not delete an uploaded theme or change a live storefront.

How a normal work session looks

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

Use Workbench to test mobile and desktop pages, every right-panel control and important commerce flows. Upload only after the local check and visual review both pass.

Common command problems

  • Theme not found: run the command from the workspace containing upstorr-workspace.json, and use the theme folder key shown inside themes/.
  • Connection invalid or expired: create a current merchant development secret in Admin and connect again.
  • Theme key not allowed: the secret was not issued for this theme. Use a permitted theme key or ask the merchant for the correct access.
  • Port already in use: pass another local port to theme dev.
  • Checkout check failed: read every listed file error, repair the authored source and run theme check again.
  • Upload completed but the live store did not change: this is expected. Upload creates a draft or available update; the merchant must review and publish it in Admin.