# 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](https://nodejs.org) 18.17 or newer. ```bash npx @hystudios/hystore login npx @hystudios/hystore theme pull npx @hystudios/hystore theme dev ``` > [!TIP] > Using it every day? Install it once with `npm install -g @hystudios/hystore` > and replace `npx @hystudios/hystore` with `hystore` in the commands. ## Step by step ### 1. Sign in to your store ```bash 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 ```bash mkdir my-store && cd my-store npx @hystudios/hystore theme pull ``` The folder looks like this: ```text 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: ```bash npx @hystudios/hystore theme new my-store ``` ### 3. Keep the preview running ```bash 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 ```bash npx @hystudios/hystore theme check ``` The same rules as the server, on your machine. An error shows the file, the line and the reason: ```text x sections/banner.liquid:3 Event attributes (onclick, onload...) are not allowed. Use data-hystore-* components. (html_event_handler) ``` ### 6. Ask to publish ```bash 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 ```bash 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 | Command | What it does | |---|---| | `login` | signs in with the code approved in the dashboard | | `logout` | ends the session on the server too | | `whoami` | shows the store and the permissions | | `theme pull` | downloads the draft to the folder, with images, fonts and the AI files | | `theme push` | checks the folder and uploads what changed since the last sync | | `theme dev` | uploads on every save and opens the preview, which reloads by itself | | `theme check` | checks on your machine, with the same rules as the server | | `theme open` | opens a preview link of the draft (24 hours) | | `theme publish` | asks to publish (`--note "..."`); approved in the dashboard | | `theme versions` | lists the last 30 published versions | | `theme rollback ` | brings version n back to the draft (`--yes` skips the question) | | `theme new [folder]` | creates a folder from the Base theme | Options: `--dir `, `--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 `.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. ```yaml .github/workflows/theme.yml 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.