@shopbb/cli

The official command-line tool for developing and deploying storefronts on the shopbb platform.

@shopbb/cli lets you link a local project to your shopbb store, manage environment variables, run a local dev server with remote data, and deploy to the global edge runtime — all without leaving your terminal.

npx @shopbb/cli link        # 关联当前项目到 shopbb 店铺
npx @shopbb/cli dev         # 本地启动 dev server（自动注入远端 env）
npx @shopbb/cli deploy      # 部署到 shopbb edge runtime

安装

无需全局安装，所有命令都可以用 npx 一次性运行：

npx @shopbb/cli <command>

也可以在项目里装一份：

npm install --save-dev @shopbb/cli
npx shopbb <command>

要求 Node.js 18+。

完整命令

shopbb link

把当前目录关联到一个 shopbb 店铺。会：

1. 打开浏览器走 device-code OAuth（参考 GitHub CLI / Shopify CLI 的体验）
2. 把 JWT 写到 ~/.shopbb/config.json
3. 选择/创建店铺
4. 把 storefront token 写到当前项目的 .env
5. 把 store_id / subdomain 写到 .shopbb.json

npx @shopbb/cli link

shopbb dev

启动本地 dev server。会先从远端拉环境变量注入到 process.env，再调当前项目 package.json 里的 dev 脚本。

npx @shopbb/cli dev
npx @shopbb/cli dev --env=preview     # 用指定环境的变量
npx @shopbb/cli dev --no-env          # 不拉远端，只用本地 .env

shopbb deploy

构建并部署当前项目到 shopbb edge runtime。每次部署都会生成一个新的 deployment_id + 独立 preview URL。

npx @shopbb/cli deploy
npx @shopbb/cli deploy --env=production

shopbb env

管理远端环境变量。

npx @shopbb/cli env list             # 列所有变量
npx @shopbb/cli env pull              # 拉远端变量写到 .env
npx @shopbb/cli env push              # 把本地 .env 推到远端

shopbb preview

本地跑 production build（用 remote env），用来在部署前自查。

npx @shopbb/cli preview

shopbb codegen

根据项目里的 GraphQL 查询生成 TypeScript 类型。

npx @shopbb/cli codegen
npx @shopbb/cli codegen --watch

shopbb upgrade

升级项目里的 @shopbb/helium 依赖到最新版。

npx @shopbb/cli upgrade           # 升级到最新
npx @shopbb/cli upgrade --check   # 只查不升级

shopbb list / shopbb ls

列出当前账号下所有店铺。

shopbb whoami

显示当前登录的账号。

shopbb logout

清掉本地 JWT。

shopbb unlink

解除当前项目的店铺关联。

配置文件

| 文件 | 位置 | 内容 | |---|---|---| | ~/.shopbb/config.json | 用户级 | JWT、当前账号 email | | .shopbb.json | 项目级 | store_id、subdomain、project name | | .env | 项目级 | storefront API token 等环境变量（由 link 写入，gitignore） |

工作流

典型一天：

# 第一次：关联店铺
cd my-storefront
npx @shopbb/cli link

# 日常：本地开发
npx @shopbb/cli dev

# 部署
npx @shopbb/cli deploy

# 看哪个变量已经设了
npx @shopbb/cli env list

# 出问题回滚（在 shopbb 后台点 rollback）

相关包

• @shopbb/helium — storefront 框架（npm install + import 使用）
• @shopbb/cli — 本包，开发部署工具

文档

完整文档：https://oxygen-demo.cloudc.top/docs/cli

营销主页：https://oxygen-demo.cloudc.top/helium

License

MIT