{"id":21826330,"url":"https://github.com/thebeyondgroup/shopkeeper","last_synced_at":"2026-03-14T01:36:25.282Z","repository":{"id":39614634,"uuid":"298427609","full_name":"TheBeyondGroup/shopkeeper","owner":"TheBeyondGroup","description":"A CLI for managing settings and deployments of Shopify store themes.","archived":false,"fork":false,"pushed_at":"2024-05-22T21:03:42.000Z","size":1587,"stargazers_count":37,"open_issues_count":1,"forks_count":3,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-05-22T21:59:28.161Z","etag":null,"topics":["cli","shopify","shopify-theme"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheBeyondGroup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-25T00:35:12.000Z","updated_at":"2024-05-22T21:03:30.000Z","dependencies_parsed_at":"2024-05-22T21:57:18.825Z","dependency_job_id":"7d7342e4-e22c-4648-b0be-b970c10a3ad3","html_url":"https://github.com/TheBeyondGroup/shopkeeper","commit_stats":{"total_commits":320,"total_committers":6,"mean_commits":"53.333333333333336","dds":"0.11250000000000004","last_synced_commit":"07ca30562632b6d3dbcf19234a902e0f480aecb7"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheBeyondGroup%2Fshopkeeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheBeyondGroup%2Fshopkeeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheBeyondGroup%2Fshopkeeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheBeyondGroup%2Fshopkeeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheBeyondGroup","download_url":"https://codeload.github.com/TheBeyondGroup/shopkeeper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248825493,"owners_count":21167493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","shopify","shopify-theme"],"created_at":"2024-11-27T18:03:41.952Z","updated_at":"2026-03-14T01:36:25.220Z","avatar_url":"https://github.com/TheBeyondGroup.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shopkeeper\n\u003ca href=\"http://twitter.com/_thebeyondgroup\"\u003e\u003cimg src=\"https://img.shields.io/twitter/follow/_thebeyondgroup?style=flat-square\" alt=\"Twitter Followers\"\u003e\u003c/a\u003e\n\u003cimg src=\"https://img.shields.io/badge/License-MIT-green.svg\" alt=\"License\"\u003e\n\nShopkeeper is a CLI to help manage Shopify stores. \n\nIt is built as an oclif plugin to allow seamless integration with the Shopify\nCLI theme developers use every day.\n\nIt helps developers:\n* Manage settings\n* Deploy theme changes\n\n## Installation\n\nYou can install the CLI globally with:\n\n```sh-session\nnpm install -g @thebeyondgroup/shopkeeper\n```\n\nOr if your theme has a `package.json`:\n\n```sh-session\nnpm add --save-dev @thebeyondgroup/shopkeeper\n```\n\nTo install Shopkeeper as a plugin to the Shopify CLI, run:\n\n```sh-session\nshopify plugins install @thebeyondgroup/shopkeeper\n```\n\n### tl;dr\n\nAssuming you've set `SHOPIFY_CLI_THEME_TOKEN`, `SHOPIFY_FLAG_STORE`,\n`SHOPIFY_FLAG_PATH`, or are setting their corresponding flags when calling a\ncommand:\n\nTo download settings from the live theme:\n```sh-session\nshopkeeper theme settings download\n```\nTo switch buckets:\n```sh-session\nshopkeeper bucket switch --bucket \u003cbucket name\u003e\n```\n\nTo deploy _directly_ to the live theme after pulling down the live theme's settings:\n```sh-session\nshopkeeper theme deploy --strategy basic\n```\n\nRead [The Complete Guide](/docs/the_complete_guide.md) for an introduction and\nwalkthrough of how to use Shopkeeper.\n\n## Commands\n\nTo learn the full capability of Shopkeeper, see the [command docs](docs/commands).\n\nWhen using it as a standalone, call commands using `shopkeeper COMMAND`.\nWhen using it as a plugin to the Shopify CLI, you can call command using `shopify COMMAND`.\n\nYou can verify Shopkeeper has been correctly installed as a plugin by running `shopify commands`.\nIf you can see the bucket commands listed, Shopkeeper is installed correctly.\n\nUse `npx` to run the version local to your project's `node_modules`.\n\nIf the commands are not showing up, reinstall the plugin.\n\n```sh-session\nshopify plugins reset\nshopify plugins install @thebeyondgroup/shopkeeper\n```\n\n## Manage Settings\n\nShopkeeper makes it easy to manage multiple Shopify stores from a single\ncodebase. In particular, it makes it easy to switch between store instances and\nmanage theme settings.\n\nIt uses a `.shopkeeper` folder at the root of your project to store buckets of settings.\n\n\u003e :brain: We refer to groups of settings as \"buckets\" because the term\n\u003e environment is overloaded in Shopify development. You might have production\n\u003e and staging store instances. These might be referred to as \"environments.\" To\n\u003e add to the confusion, Shopify recently added the ability to specify groups of\n\u003e flags in a `shopify.theme.toml` file and calls these groups\n\u003e [environments](https://shopify.dev/docs/themes/tools/cli/environments).\n\u003e\n\u003e Therefore, we call our groups of settings buckets. :bucket:\n\nIn multi-store, multi-region setups, you might have a bucket for\neach region. Say `canada`, `united-states`, or `united-kingdom`. Or you might\nuse a bucket to contains the settings for an A/B test.\n\nHere we see an example `production` bucket created from the default \ninstallation of [Dawn](https://github.com/shopify/dawn):\n\n```sh-session\n.shopkeeper\n├── production\n│   ├── config\n│   │   └── settings_data.json\n│   ├── sections\n│   │   ├── footer-group.json\n│   │   └── header-group.json\n│   ├── templates\n│   │   ├── customers\n│   │   │   ├── account.json\n│   │   │   ├── activate_account.json\n│   │   │   ├── addresses.json\n│   │   │   ├── login.json\n│   │   │   ├── order.json\n│   │   │   ├── register.json\n│   │   │   └── reset_password.json\n│   │   ├── 404.json\n│   │   ├── article.json\n│   │   ├── blog.json\n│   │   ├── cart.json\n│   │   ├── collection.json\n│   │   ├── index.json\n│   │   ├── list-collections.json\n│   │   ├── page.contact.json\n│   │   ├── page.json\n│   │   ├── password.json\n│   │   ├── product.json\n│   │   └── search.json\n│   ├── .env\n│   └── .env.sample\n└── .current-bucket\n```\n\nEach bucket contains theme settings stored in their corresponding `config`,\n`sections`, and `templates` folders. It also contains a `.env` file that's\ncopied to the project root as `.env ` when the bucket is switched.\n\n## Deploy Changes\n\nShopkeeper supports multiple deployment strategies:\n\n* Basic\n* Blue/Green\n\nShopkeeper extends the Shopify CLI `theme` topic with a \n[`deploy`](docs/commands/readme.md#shopkeeper-theme-deploy) command.\n\n### Basic Deployment\n\nWhen you run `shopkeeper theme deploy --strategy basic`, Shopkeeper will:\n1. Download settings from the live theme\n2. Push code to the live theme\n3. Update the live theme's name to be `[HEAD_SHA] Production`\n\n\u003e :warning: the default deployment strategy is `blue-green`, so the `--strategy` must be set.\n\n### Blue/Green Deployment\n\nA blue/green deployment strategy alternates between a blue and a green theme.\nOne theme is live and the other we refer to as on-deck. For example, using this\napproach, if a the blue :large_blue_circle: theme is live, the green\n:green_circle: theme is on-deck.\n\nWhen you run `shopkeeper theme deploy`, Shopkeeper will:\n\n1. Download settings from the live theme\n2. Push code to the on-deck theme\n3. Rename the on-deck theme to be `[\u003cHEAD_SHA\u003e] Production - \u003ccolor\u003e`\n\nUsing blue/green deploys requires additional setup. You must specify the theme IDs for the blue\nand green themes. You can pass these values as flags:\n\n```sh-session\nshopkeeper theme deploy --blue 13455343 --green 654321\n\n```\n\nA better option is to set the flags in the bucket's `.env` file. Every flag in\nthe Shopify CLI can be set with an environment variable. Shopkeeper follows\nthis pattern:\n\n| Flag                  | Use                                   |\n| ---------------------- | ------------------------------------- |\n| `SKR_FLAG_BLUE_THEME_ID`| blue theme ID, cannot be name as name will be update   |\n| `SKR_FLAG_GREEN_THEME_ID`| green theme ID, cannot be name as name will be update   |\n\nUsing a tool like [mise](https://mise.jdx.dev/environments/), you can have your environment variables automatically\nupdated when you switch buckets.\n\nSetting the following in your shell is a great way to reduce the config needed in your repo.\n```\nMISE_ENV_FILE=.env \n ```\n\n## Contribute\nIf you'd like to contribute to the project, check out the [contributors docs](docs/contribute.md) to get started.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthebeyondgroup%2Fshopkeeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthebeyondgroup%2Fshopkeeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthebeyondgroup%2Fshopkeeper/lists"}