hystore tool

@hystudios/hystore edits your store's code theme on your computer, with the AI you already use (Claude Code, Cursor, Codex, Copilot) and with git. It only needs Node.js 18.17 or newer.

npx @hystudios/hystore login
npx @hystudios/hystore theme pull
npx @hystudios/hystore theme dev

Step by step

1. Sign in to your store

npx @hystudios/hystore login

1. The tool shows an 8-letter code and opens the dashboard in the browser.
2. Check that the code in the dashboard is the same as in the terminal.
3. Pick the store and what the tool may do (read, edit the draft, ask to publish).
4. Click Authorize. The terminal shows the connected store.

There is no token to copy or paste. The code lasts 10 minutes and works once.

2. Download the theme

mkdir my-store && cd my-store
npx @hystudios/hystore theme pull

The folder looks like this:

my-store/
  theme.json
  layout/theme.liquid
  pages/home.liquid
  sections/hero.liquid
  styles/theme.css
  locales/pt.json  en.json  es.json
  assets/logo.webp
  apps/roleta/index.html
  AGENTS.md                         rules and guide for the AI
  CLAUDE.md                         the same, for Claude Code
  .cursor/rules/hystore-theme.mdc   for Cursor
  .claude/skills/hystore-theme/SKILL.md

A store without a theme? Use theme new to start from the Base theme:

npx @hystudios/hystore theme new my-store

3. Keep the preview running

npx @hystudios/hystore theme dev

It checks and uploads every file you save and opens the preview on the store's address, which reloads by itself. Keep this terminal open while you work.

4. Edit, you or your AI

Open the folder in your editor and ask the AI, for example: "Make a Black Friday banner at the top of the home, in the store's colours, with texts in pt, en and es." It reads AGENTS.md (or CLAUDE.md) and follows the theme rules.

5. Check

npx @hystudios/hystore theme check

The same rules as the server, on your machine. An error shows the file, the line and the reason:

  x sections/banner.liquid:3  Event attributes (onclick, onload...) are not allowed. Use data-hystore-* components. (html_event_handler)

6. Ask to publish

npx @hystudios/hystore theme publish --note "Black Friday banner"

This creates a publish request. Whoever has the Publish the theme permission opens Customization > Code theme > Publish requests, sees what changed and approves.

7. Keep it in git

git init && git add . && git commit -m "Store theme"

No file in the folder has a token or a key: it can go to a repository. The tool already puts in .gitignore what should not go (.hystore/, with the sync state, and the *.remote copies).

Commands

Options: --dir <folder>, --force, --no-open, --lang pt|en|es. hystore pull works like hystore theme pull.

The session

• It lasts 30 days and renews itself. It shows in Customization > Theme access > Connected sessions, where it can be disconnected.
• It lives in your user folder (~/.config/hystore, or %APPDATA%\hystore on Windows), which only you can read. Never in the theme folder.
• For every new login, the store owner gets an e-mail with the link to disconnect.

Conflicts

Each upload carries the version of each file you last downloaded. If someone changed that file in the dashboard meanwhile, the upload is refused instead of overwriting it. Run theme pull:

• what changed only in the store comes in;
• what changed only here stays;
• a file changed in both places keeps yours, with the store's copy next to it as <file>.remote. Merge, delete the .remote and upload again.

theme push --force overwrites the store's version; theme pull --force makes the folder equal to the store.

In CI (GitHub Actions)

For CI, create a key in Customization > Theme access > Create key (scopes read and edit, and request a publish if CI will ask) and keep it in the repository secrets as HYSTORE_THEME_TOKEN. The tool uses that variable instead of the login.

name: theme
on:
  push:
    branches: [main]
jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx @hystudios/hystore theme check
      - run: npx @hystudios/hystore theme push --force
        env:
          HYSTORE_THEME_TOKEN: ${{ secrets.HYSTORE_THEME_TOKEN }}
      - run: npx @hystudios/hystore theme publish --note "Commit ${{ github.sha }}"
        env:
          HYSTORE_THEME_TOKEN: ${{ secrets.HYSTORE_THEME_TOKEN }}

• --force: in CI git is the source of truth, and the cloned folder has no sync state (.hystore/, which stays out of git). The upload writes the folder over the draft.
• The last step only creates the request: the store changes when someone approves it in the dashboard.

Security

• Publishing is always a request approved in the dashboard.
• The tool only reads and writes theme files in the folder; other files are left alone.
• Images and fonts are only downloaded from Hystore's address and checked by their hash.