LocalStage CLI

LocalStage is the CLI for running a local theme development server. It renders your theme files using the same engine as production, with live reload while you edit.

What you'll set up

• The LocalStage CLI installed locally.
• A connection to your Basker site.
• A local dev server with live reload.
• Theme validation from the dev server.

Prerequisites

• Node.js 22.12 or newer.
• A Basker site with login credentials.
• A theme directory with layouts/, templates/, and blocks/.

Step 1 — Install the CLI

npm install -g @baskerhq/localstage

Verify:

basker --version
# @baskerhq/localstage/1.0.x

Step 2 — Start the development server

From inside your theme directory:

cd ./my-theme
basker theme dev

Or specify the path explicitly:

basker theme dev --theme ./my-theme

If this is your first run, LocalStage prompts for your Basker email and password directly in the terminal, then asks which workspace to use. The session is cached per theme directory so you won't be asked again.

Once authenticated, you should see a summary box:

╭─ success ─────────────────────────────────────────────╮
│                                                       │
│ Preview your theme                                    │
│   • http://localhost:9292                             │
│   • Browser sync: http://localhost:9292               │
│                                                       │
│ Next steps                                            │
│   • Open or re-sync browser (o) http://localhost:9292 │
│   • Run theme checks (c) basker theme check           │
│   • Set theme ID (p) basker theme set --theme-id <id> │
│   • Clear API cache (r) drop cached CMS responses     │
│                                                       │
│ Local details                                         │
│   • Theme path: /path/to/my-theme                     │
│   • CMS: https://basker.app                           │
│   • Live reload: On                                   │
│   • Quit (q) Stop LocalStage                          │
╰───────────────────────────────────────────────────────╯

LocalStage opens your default browser at http://localhost:9292 automatically. Keep the terminal open while you work.

If you see "No theme files detected in current directory", LocalStage couldn't find layouts/ or templates/ in the current path. Either cd into the theme directory first, or pass --theme ./my-theme.

Step 3 — Confirm the preview is rendering

The browser should now show your theme rendered against live CMS data. Press o in the terminal to re-open or re-sync the tab if you've closed it.

If the page looks unstyled or has missing content, that's expected for a new theme — you don't have content to render yet.

To reset the cached session and sign in as a different user, run basker auth logout (or basker auth login to re-authenticate without restarting the dev server).

Step 4 — Set the theme to preview (optional)

If your theme is already uploaded to Basker, link the local server to the remote theme record so LocalStage can load theme settings from the CMS.

Press p in the dev-server terminal and enter the theme ID. You can find it in Design → Themes in the admin.

Or use theme set to look up the ID automatically by theme key (the directory name):

basker theme set --theme ./my-theme

Automatic lookup uses the auth session cached by theme dev, so make sure you've run the dev server at least once first. You can also pass an explicit ID with --theme-id <id>.

Setting a theme ID is optional. Without it, LocalStage uses a local fallback theme.

Step 5 — Edit a template and see live reload

Open a .liquid file in your editor. Add a paragraph to layouts/default.liquid:

<p>Hello from Basker!</p>

Save the file. Switch to your browser — the page should refresh within a second.

LocalStage watches .liquid, .css, .js, .json, and .html files. When a file changes, it sends a reload signal via a WebSocket on port 9293 (one above the main server).

Disable live reload with --no-livereload if you prefer manual refreshes:

basker theme dev --theme ./my-theme --no-livereload

Step 6 — Run theme validation

While the dev server is running, press c to run the theme checker against your local files:

Theme check: 0 errors, 2 warnings, 0 info
- [warning] templates/page.liquid: Template is missing a schema tag.
- [warning] blocks/text-section.liquid: Block schema missing singular label.

Or run validation as a standalone command in another terminal:

basker theme check --theme ./my-theme

For CI, use --fail-level to control which severity exits non-zero:

basker theme check --theme ./my-theme --fail-level warning

Exit code 0 means no issues at or above the level. Exit code 1 means at least one matched.

Next steps

• Tutorial — if you skipped here.
• Theme directory structure — required and optional directories.
• Uploading themes — package and deploy.

Troubleshooting

"No theme files detected in current directory"

LocalStage looks for layouts/ or templates/ in the current working directory. Either cd into the theme directory first, or pass --theme ./subdirectory-name.

"Failed to locate theme"

The path passed to --theme doesn't exist or isn't a directory. Double-check for typos; an absolute path can help if relative paths aren't resolving.

"Error verifying session"

LocalStage couldn't validate your auth token. Run basker auth logout followed by basker auth login (or restart basker theme dev) to refresh the session.

Port 9292 is already in use

Another process is using the port. Stop it, or run on a different port: basker theme dev --port 9300.

WebSocket connection refused on port 9293

Live reload uses the port immediately after the main server. If it's in use, the dev server keeps running but live reload won't fire. Stop whatever's on 9293, or change the main port (--port 9300 makes the WebSocket use 9301).