climaybe

Shopify CI/CD CLI — scaffolds GitHub Actions workflows, branch strategy, and store config for single-store and multi-store theme repositories.

Commit linting and AI-assisted commits are available as optional setup steps:

Conventional commit linting: During climaybe init, you can choose to automatically install and configure commitlint and Husky to enforce Conventional Commits in your theme repository.
Cursor AI commit skill: You can also opt-in to installing the Cursor AI commit skill (.cursor/skills/commit/SKILL.md) for AI-assisted, conventional commit message support in your project.

Both options streamline commit message quality and team workflows but are fully optional during setup.

Install

Install in your theme repo (project-only, no global install):

cd your-shopify-theme-repo
npm install -D climaybe

Run commands with npx climaybe (or add scripts to your package.json).

Quick Start

cd your-shopify-theme-repo
npm install -D climaybe
npx climaybe init

The interactive setup will ask for your store URL(s) and configure everything automatically.

Commands

`climaybe init`

Interactive setup that configures your repo for CI/CD.

Prompts for your store URL (e.g., voldt-staging.myshopify.com)
Extracts subdomain as alias, lets you override
Asks if you want to add more stores
Asks whether to enable optional preview + cleanup workflows (default: yes)
Asks whether to enable optional build + Lighthouse workflows (default: yes)
Asks whether to enable commitlint + Husky (enforce conventional commits on git commit)
Asks whether to add Cursor commit skill to the project (.cursor/skills/commit/SKILL.md) for AI-assisted conventional commits
Based on store count, sets up single-store or multi-store mode
Writes package.json config
Scaffolds GitHub Actions workflows
Creates git branches and store directories (multi-store)
Optionally installs commitlint, Husky, and the Cursor skill

`climaybe add-store`

Add a new store to an existing setup.

npx climaybe add-store

Prompts for new store URL + alias
Creates staging-<alias> and live-<alias> branches
Creates stores/<alias>/ directory structure
If store count goes from 1 to 2+, automatically migrates from single to multi-store mode

`climaybe switch <alias>`

Switch your local dev environment to a specific store (multi-store only).

npx climaybe switch voldt-norway

Copies stores/<alias>/ JSON files to the repo root so you can preview that store locally.

`climaybe sync [alias]`

Sync root JSON files back to a store directory (multi-store only).

npx climaybe sync voldt-norway

If no alias is given, syncs to the default store.

`climaybe ensure-branches`

Create missing staging and per-store branches (staging-<alias>, live-<alias>) from your current branch (usually main). Use when the repo only has main (e.g. after a fresh clone) so the main → staging-<store> sync can run.

npx climaybe ensure-branches
git push origin --all

`climaybe update-workflows`

Refresh GitHub Actions workflows from the latest bundled templates.

npx climaybe update-workflows

Useful after updating the CLI to get the latest workflow improvements.

`climaybe setup-commitlint`

Set up only commitlint + Husky (conventional commits enforced on git commit). Use this if you skipped it at init or want to add it later.

npx climaybe setup-commitlint

`climaybe add-cursor-skill`

Add only the Cursor commit skill to this project (.cursor/skills/commit/SKILL.md). Use this if you skipped it at init or want to add it later.

npx climaybe add-cursor-skill

Configuration

The CLI writes config into the config field of your package.json:

{
  "config": {
    "port": 9295,
    "default_store": "voldt-staging.myshopify.com",
    "preview_workflows": true,
    "build_workflows": true,
    "commitlint": true,
    "cursor_skills": true,
    "stores": {
      "voldt-staging": "voldt-staging.myshopify.com",
      "voldt-norway": "voldt-norway.myshopify.com"
    }
  }
}

Workflows read this config at runtime — no hardcoded values in YAML files.

Branch Strategy

Single-store

staging → main

staging — development branch
main — production branch

Multi-store

staging → main → staging-<store> → live-<store>

staging — development branch
main — shared codebase (not live)
staging-<store> — per-store staging with store-specific JSON data
live-<store> — per-store production

Direct pushes to staging-<store> or live-<store> are automatically synced back to main (no PR; multistore-hotfix-to-main merges the branch into main).

Workflows

Shared (both modes)

Workflow	Purpose
`ai-changelog.yml`	Reusable workflow. Sends commits to Gemini API, returns classified changelog.
`version-bump.yml`	Reusable workflow. Bumps version in `settings_schema.json`, creates git tag.

Single-store

Workflow	Trigger	What it does
`release-pr-check.yml`	PR from `staging` to `main`	Finds latest tag on main, AI changelog to PR head, creates pre-release patch tag (e.g. v3.1.13) to lock state; posts changelog comment
`post-merge-tag.yml`	Push to `main` (merged PR)	Staging→main only: minor bump from latest tag (e.g. v3.1.13 → v3.2.0). No version in PR title
`nightly-hotfix.yml`	Cron 02:00 US Eastern	Collects commits since latest tag (incl. hotfix backports), AI changelog, patch bump and tag

Multi-store (additional)

Workflow	Trigger	What it does
`main-to-staging-stores.yml` (main-to-staging-<store>)	Push to `main`	Merges main into each `staging-<alias>`; root JSONs ignored. For hotfix-backport, skips the store that sent the hotfix; other stores get the merge. Skips only on pure store-sync.
`stores-to-root.yml`	Push to `staging-*`	From main merge: stores→root. From elsewhere (e.g. Shopify): root→stores
`pr-to-live.yml`	After stores-to-root	Opens PR from `staging-<alias>` to `live-<alias>`
`root-to-stores.yml`	Push to `live-*`	From main merge: stores→root. From elsewhere: root→stores (same as stores-to-root on staging-*)
`multistore-hotfix-to-main.yml`	Push to `staging-` or `live-` (and after root-to-stores)	Merges store branch into main (no PR). Skips when push is a merge from main (avoids loop)

Optional preview + cleanup package

Enabled via climaybe init prompt (Enable preview + cleanup workflows?; default: yes).

Workflow	Trigger	What it does
`pr-update.yml`	PR opened/synchronize/reopened (base: main, staging, develop, staging-, live-)	Shares draft theme, renames with `-PR<number>`, comments preview + customize URLs; uses default store for main/staging/develop, or the store for staging-<alias>/live-<alias>
`pr-close.yml`	PR closed (same branch set)	Deletes matching preview themes and comments deleted count + names
`reusable-share-theme.yml`	workflow_call	Shares Shopify draft theme and returns `theme_id`
`reusable-rename-theme.yml`	workflow_call	Renames shared theme to include `PR<number>` (fails job on rename failure)
`reusable-comment-on-pr.yml`	workflow_call	Posts preview comment including Customize URL
`reusable-cleanup-themes.yml`	workflow_call	Deletes preview themes by PR number and exposes cleanup outputs
`reusable-extract-pr-number.yml`	workflow_call	Extracts padded/unpadded PR number outputs for naming and API-safe usage

Optional build + Lighthouse package

Enabled via climaybe init prompt (Enable build + Lighthouse workflows?; default: yes).

Workflow	Trigger	What it does
`build-pipeline.yml`	Push to `main/staging/develop`	Runs reusable build and Lighthouse checks (when required secrets exist)
`reusable-build.yml`	workflow_call	Runs Node build + Tailwind compile, then commits compiled assets when changed
`create-release.yml`	Push tag `v*`	Builds release archive and creates GitHub Release using `release-notes.md`

Versioning

Version format: Always three-part (e.g. v3.2.0). No version in code or PR title; the system infers from tags.
No tags yet? The system uses theme_version from config/settings_schema.json (theme_info), creates that tag on main (e.g. v1.0.0), and continues from there.
Staging → main: On PR, a pre-release patch tag (e.g. v3.1.13) locks the current minor line; on merge, minor bump (e.g. v3.1.13 → v3.2.0).
Non-staging to main (hotfix backports, direct commits): Patch bump only, via nightly workflow at 02:00 US Eastern (not at commit time).
Version bump runs only on main (post-merge-tag and nightly-hotfix). Main-to-staging-stores merges main into each staging-<alias> on every push (version bumps and hotfixes). When the push is a hotfix from one store (e.g. live-norway), that store’s staging branch is skipped; other stores’ staging branches still get the merge.
Version bumps update config/settings_schema.json and, when present, package.json version.

Full specification: For detailed versioning rules, local dev flow, hotfix behavior, and alignment with the external CI/CD doc, see CI/CD Reference.

File Sync Rules (Multi-store)

Synced between root and stores/<alias>/:

config/settings_data.json
templates/*.json
sections/*.json

NOT synced (travels via branch history):

config/settings_schema.json
locales/*.json

Recursive Trigger Prevention

Hotfix sync merge commits (multistore-hotfix-to-main) contain [hotfix-backport] in the message
Store sync commits contain [stores-to-root] or [root-to-stores]
Version bump commits contain chore(release): bump version
All workflows check for these flags and skip accordingly

GitHub Secrets

Add the following secrets to your GitHub repository (or use GitLab CI/CD variables if you use GitLab). You can configure them during climaybe init via the GitHub or GitLab CLI.

Secret	Required	Description
`GEMINI_API_KEY`	Yes	Google Gemini API key for changelog generation
`SHOPIFY_STORE_URL`	Set from config	Store URL is set automatically from the store domain(s) you add during init (no prompt).
`SHOPIFY_THEME_ACCESS_TOKEN`	Yes*	Theme access token for preview workflows (required when preview is enabled).
`SHOP_ACCESS_TOKEN`	Optional*	Required only when optional build workflows are enabled (Lighthouse)
`LHCI_GITHUB_APP_TOKEN`	Optional*	Required only when optional build workflows are enabled (Lighthouse)
`SHOP_PASSWORD`	Optional	Used by Lighthouse action when your store requires password auth

Store URL: During climaybe init (or add-store), store URL secret(s) are set from your configured store domain(s); you are only prompted for the theme token.

Multi-store: Per-store secrets SHOPIFY_STORE_URL_<ALIAS> and SHOPIFY_THEME_ACCESS_TOKEN_<ALIAS> — the URL is set from config; you must provide the theme token per store. <ALIAS> is uppercase with hyphens as underscores (e.g. voldt-norway → SHOPIFY_STORE_URL_VOLDT_NORWAY). Preview and cleanup: for PRs targeting main, staging, or develop the workflows use the default store (from config.default_store or first in config.stores); for PRs targeting staging-<alias> or live-<alias> they use that store’s credentials. Set either the plain SHOPIFY_* secrets or the _<ALIAS> pair for each store you use in preview.

Directory Structure (Multi-store)

├── assets/
├── config/
├── layout/
├── locales/
├── sections/
├── snippets/
├── templates/
├── stores/
│   ├── voldt-staging/
│   │   ├── config/settings_data.json
│   │   ├── templates/*.json
│   │   └── sections/*.json
│   └── voldt-norway/
│       ├── config/settings_data.json
│       ├── templates/*.json
│       └── sections/*.json
├── package.json
└── .github/workflows/

Releases and versioning

Branch: Single default branch main. Feature branches open as PRs into main.
Versioning: SemVer. Versions are bumped automatically when PRs are merged to main using conventional commits: fix: → patch, feat: → minor, BREAKING CHANGE or feat!: → major.
Flow: Merge to main → Release version runs semantic-release (bumps package.json, pushes tag) → tag push triggers Release (tests + publish to npm). Requires NPM_TOKEN secret for npm publish. Do not create tags manually; only the Release version workflow creates tags so that tag and package version stay in sync.
CI: Every PR and push to main runs tests on Node 20 and 22 (CI workflow).

See CONTRIBUTING.md for branch, PR, and conventional-commit details.

License

MIT — Electric Maybe

Name		Name	Last commit message	Last commit date
Latest commit History 94 Commits
.cursor/rules		.cursor/rules
.github		.github
.husky		.husky
bin		bin
docs		docs
node_modules		node_modules
scripts		scripts
src		src
tests		tests
.DS_Store		.DS_Store
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
WORKFLOW_UPDATES.md		WORKFLOW_UPDATES.md
commitlint.config.js		commitlint.config.js
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

climaybe

Install

Quick Start

Commands

climaybe init

climaybe add-store

climaybe switch <alias>

climaybe sync [alias]

climaybe ensure-branches

climaybe update-workflows

climaybe setup-commitlint

climaybe add-cursor-skill

Configuration

Branch Strategy

Single-store

Multi-store

Workflows

Shared (both modes)

Single-store

Multi-store (additional)

Optional preview + cleanup package

Optional build + Lighthouse package

Versioning

File Sync Rules (Multi-store)

Recursive Trigger Prevention

GitHub Secrets

Directory Structure (Multi-store)

Releases and versioning

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`climaybe init`

`climaybe add-store`

`climaybe switch <alias>`

`climaybe sync [alias]`

`climaybe ensure-branches`

`climaybe update-workflows`

`climaybe setup-commitlint`

`climaybe add-cursor-skill`

Packages