Stayblox Developer Platform

Appearance

Stayblox CLI ​

@stayblox/cli is the developer CLI for building and publishing marketplace themes. It validates your theme against the platform's real rules, pushes versions as private drafts, and submits them for review, all from the theme directory.

Building a theme just for your own storefront? You don't need the CLI. Upload a .zip in your admin instead. See Publishing → custom themes.

Install ​

bash
npm install -g @stayblox/cli

Requires Node 20+.

Authenticate ​

bash
stayblox login

login prompts for your platform email and password and stores an API token in ~/.config/stayblox/config.json.

The theme commands require your user to belong to a verified partner account. If you belong to several partner accounts, pass --account <id> to any theme command.

The theme.json manifest ​

Every theme is identified by a theme.json manifest in the theme root, the same contract whether you publish with the CLI or upload a .zip to a site:

json
{
  "slug": "breeze",
  "name": "Breeze",
  "version": "1.0.0",
  "description": "A light, airy hotel theme."
}
  • slug: 2–40 chars of lowercase letters, digits and dashes, starting and ending with a letter or digit. Permanently yours after the first push; nobody else can publish to it.
  • version: strict semver (major.minor.patch). Bump it for every release.
  • changelog: optional; stored on the version when present.

Commands ​

Run these from the theme directory; the commands that read your theme accept --path <dir> to point elsewhere:

bash
stayblox theme init my-theme     # scaffold a minimal starter theme
stayblox theme validate          # server-side validation, nothing published
stayblox theme push              # publish a draft version (private until approved)
stayblox theme push --submit     # publish and submit for review in one go
stayblox theme list              # your themes on the platform
stayblox theme versions          # versions + review status for this theme
stayblox theme version 1.2.0     # one version's status, notes, and full report
stayblox theme delete 1.2.0      # delete a draft version (drafts only)
stayblox theme dev               # live development against one of your storefronts

validate and push upload your theme as a package and return a structured report of errors and warnings; see Publishing → validation for what's checked. push refuses a failing package; warnings don't block.

AI coding agents ​

stayblox mcp starts the dev MCP server for AI coding agents; see Building themes with AI.

bash
stayblox mcp

Start a theme ​

bash
stayblox theme init my-theme

scaffolds the smallest valid theme: theme.json (you're prompted for slug and name), layout/theme.liquid, a starter views/index.liquid, the config/*.json files, locales/en.json, and an empty assets/ directory. It passes stayblox theme validate as-is; from there, build it out following Theme structure.

Live development ​

bash
stayblox theme dev                    # pick a storefront interactively
stayblox theme dev --team <slug>      # or pass the team slug (see `GET /partner/teams`)

theme dev syncs the theme directory to a private dev theme on one of your own storefronts and prints a signed preview URL. Open it and keep editing: every save uploads just the changed file, and the preview tab reloads itself within about a second. Deleting a file locally removes it from the dev theme too.

Dev themes are invisible to visitors, keep the same dev theme across theme dev runs, and are pruned automatically after 30 days without changes. The underlying endpoints are documented in the Partner API.

Inspect and clean up versions ​

bash
stayblox theme version 1.2.0     # status, review notes, full validation report
stayblox theme delete 1.2.0      # remove a draft (asks to confirm; --yes skips)

Only draft versions can be deleted; approved and rejected versions are immutable history. Deleting the last draft of a theme that never released removes the theme from your account entirely.

What gets packaged ​

Only platform-supported file types are included:

  • Text: liquid, css, js, json, svg, html, txt, xml, graphql
  • Binary: woff, woff2, ttf, eot, png, jpg, jpeg, gif, ico, webp, mp4, webm. Imported and stored, but not currently served back at a URL; see Assets.

.git, node_modules, dist, vendor, and dotfiles are always excluded. The packaged .zip must stay under 20 MB.

Releases are immutable ​

Draft versions can be re-pushed freely while you iterate. Once a version is approved or rejected it is frozen: bump version in theme.json to push again. The platform rejects a push that reuses a released version name.

© Stayblox — Developer Platform