shoplazza-cli 1.1.2 → 2.0.0

package/README.md

@@ -1,444 +1,318 @@
-<p align="center">
-  <h3 align="center">Shoplazza CLI</h3>
-  <p align="center">Shoplazza CLI is a command-line interface tool that helps you build Shoplazza themes. It quickly generates Shoplazza themes. You can also use it to automate many common development tasks.</p>
-  <p align="center">
-    <img src="https://img.shields.io/npm/v/shoplazza-cli">
-  </p>
-</p>
+# shoplazza-cli
 
----
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Go Version](https://img.shields.io/badge/go-%3E%3D1.24-blue.svg)](https://go.dev/)
+[![npm version](https://img.shields.io/npm/v/shoplazza-cli.svg)](https://www.npmjs.com/package/shoplazza-cli)
 
-Shoplazza CLI is a cross-platform command line tool that you can use to build Shoplazza themes.
+[中文版](./README.zh.md) | [English](./README.md)
 
-## Features
-
-Shoplazza CLI accelerates your theme development process with the following features:
-
-- Safely preview, test, and share changes to themes using unpublish themes
-- Hot reload CSS and section changes, or automatically refresh a page on file change, when previewing a theme.
-- Initialize a new theme using Nova 2023 as a starting point.
-- Use workflow tools like Git to work with a team of theme developers.
-- Upload themes to your store.
-- Watch for local changes and upload them automatically to Shoplazza.
-- Work on Linux, macOS, and Windows.
-- Support customized Checkout page.
-
-## Installation [shoplazza-cli](https://www.npmjs.com/package/shoplazza-themekit)
-
-```terminal
-$ npm install shoplazza-cli -g
-```
-
-## Before you start
+The official [Shoplazza Open Platform](https://www.shoplazza.dev/) CLI tool — built for humans and AI Agents. Develop apps and themes, manage products, discounts, orders and customers, all from the terminal with structured output designed for AI Agent integration.
 
-Before you start using Shoplazza CLI to develop themes, make sure that you do the following tasks:
+[Install](#installation--quick-start) · [Auth](#authentication) · [Development](#development-workflows) · [Commands](#three-layer-command-system) · [Advanced](#advanced-usage) · [Contributing](#contributing)
 
-- Install [Node.js](https://nodejs.org/en/) (20.18.0).
-- Install [Git](https://git-scm.com/downloads).
-- Make sure that you have a account with the Manage themes permission for the store that you want to work on, or you're the owner of the store.
-- Note the URL of the store that you want to work on.
-- Make sure that you're connected to the internet. Most Shoplazza CLI commands need an internet connection to run.
+## Why shoplazza-cli?
 
+- **Agent-Native Design** — Structured JSON output out of the box; AI Agents can operate Shoplazza stores with zero extra setup
+- **E-Commerce Focused** — Products, Discounts, Orders, Customers with full CRUD and 20+ shortcut commands for high-frequency operations
+- **Full Developer Workflow** — App creation, extension scaffolding (checkout / theme / function), local dev server with HMR, one-command deploy; plus theme init, live reload, and packaging
+- **Secure & Controllable** — Input injection protection, OS-native keychain credential storage, token auto-refresh
+- **Three-Layer Architecture** — Shortcuts (human & AI friendly) → API Commands (OpenAPI-synced) → Raw API (full coverage)
+- **Up and Running in 3 Minutes** — Interactive login, from install to first API call in 3 steps
 
-## Checkout Develop
+## Features
 
-You  can use Shoplazza CLI  to develop checkout, customized checkout page as you want.
+| Domain | Capabilities |
+|--------|-------------|
+| 🛍️ Products | CRUD + shortcuts: `+search`, `+publish`, `+unpublish`, `+create`, `+set-price`, `+stock` |
+| 🏷️ Discounts | CRUD + 8 shortcut creators for automatic & code discounts |
+| 📦 Orders | CRUD + shortcuts: `+search`, `+count`, `+ship`, `+refund`, `+update-tracking` |
+| 👤 Customers | CRUD + shortcuts: `+search`, `+create` |
+| 🎨 Themes | `init`, `serve` (live reload), `pull`, `push`, `package`, `share` |
+| 🧩 App | Full lifecycle: init → extension create → dev → deploy; extensions: checkout, theme, function |
 
-### Feature
+## Installation & Quick Start
 
-- 支持本地开发和调试，支持热更新。
-- 支持预览，在推送到店铺之后，通过预览链接进入可以进行预览。
-- 支持部署extension，部署后所有用户都能看到变更。
-- 支持下线extension，下线之后extension将不在店铺中生效。
+### Install
 
-### Get Started
+| Method | Command | Notes |
+|--------|---------|-------|
+| **Homebrew** (macOS / Linux) | `brew install Shoplazza/tap/shoplazza-cli` | Recommended. Auto-updates via `brew upgrade`. |
+| **Shell script** (macOS / Linux) | `curl -fsSL https://raw.githubusercontent.com/Shoplazza/shoplazza-cli/main/install.sh \| bash` | Auto-detects OS and architecture. |
+| **npm** | `npm install -g @shoplazza/cli` | Requires Node.js `>=14.18.0`. |
+| **Download binary** | See [GitHub Releases](https://github.com/Shoplazza/shoplazza-cli/releases) | Manual download for any platform. |
+| **Build from source** | `git clone ... && cd shoplazza-cli && make install` | Requires Go `v1.24`+. Installs to `~/.local/bin`. |
 
-#### Step 1: 创建一个项目模板
+<details>
+<summary>Platform-specific binary download</summary>
 
-创建过程会要求你输入店铺地址和token，token可以在后台中应用->管理私有应用->创建应用 获得。创建过程还要求你输入一个extension名字，一个项目下支持存在多个extension，这是为了方便管理，它们互不影响。
 ```bash
-shoplazza checkout create
-# 安装依赖
-npm i
-```
-
-#### Step2: 本地开发
-extension支持本地开发，支持在线上店铺Checkout页面插入本地的extension代码，这仅在你的浏览器生效。
-首先，先启动本地开发服务器：
-```
-shoplazza checkout dev
-```
-然后在checkout页面打开控制台切换为开发模式：
-```
-CheckoutAPI.extension.DEV_switchDevMode()
-```
-在checkout页面即可看到extension变更。
-
-#### Step3: 预览extension
-在完成本地开发之后，我们可以将extension推送到店铺进行预览。
-```
-shoplazza checkout push
-```
-访问预览url即可看到效果。
-#### Step4: 部署Extension
-在预览测试完成之后，可以在店铺发布extension，发布之后所有用户都可以看到。
-```
-shoplazza checkout deploy
-```
-或者对将已发布的extension下线：
-```
-shoplazza checkout undeploy
-
-```
-
-### Other command
-
-#### 查看已部署的extension
-```
-shoplazza checkout list
-
-// 查看所有
-shoplazza checkout list -a
-```
-
-#### 预览extension
-```
-shoplazza checkout preview
-```
-
-## Theme Develop
-
-### Authenticate
-
-```terminal
-$ shoplazza login --store developer.myshoplaza.com
-```
-
-> In your browser window, log into the account that's attached to the store that you want to use for development.
-
-### Create a new theme
-
-```terminal
-$ shoplazza theme init
-```
-
-> Use `shoplazza theme init` to create a new theme on your local machine. This command clones a Git repository to your local machine to use as the starting point for building a theme.
-
-### Connect to existing theme
-
-```terminal
-$ shoplazza theme pull
-```
-
-> Pull the theme onto your local machine using `shoplazza theme pull`. You're prompted to select a theme from the list of themes on the store.
-
-### Preview, test, and share your theme
-
-```terminal
-$ shoplazza theme serve
-```
-
-> After you create or navigate to your theme, you can run `shoplazza theme serve` to interact with the theme in a browser.
-
-### Push your theme to your store
-
-```terminal
-$ shoplazza theme push
-```
+# macOS (Apple Silicon)
+curl -fsSL https://github.com/Shoplazza/shoplazza-cli/releases/latest/download/shoplazza-cli-darwin-arm64.tar.gz | tar -xz
+sudo install -m755 shoplazza /usr/local/bin/
 
-> Use `shoplazza theme push` to upload your local theme files to Shoplazza, overwriting the remote versions.
+# macOS (Intel)
+curl -fsSL https://github.com/Shoplazza/shoplazza-cli/releases/latest/download/shoplazza-cli-darwin-amd64.tar.gz | tar -xz
+sudo install -m755 shoplazza /usr/local/bin/
 
-### Publish your theme
+# Linux (x86_64)
+curl -fsSL https://github.com/Shoplazza/shoplazza-cli/releases/latest/download/shoplazza-cli-linux-amd64.tar.gz | tar -xz
+sudo install -m755 shoplazza /usr/local/bin/
 
-```terminal
-$ shoplazza theme publish
+# Linux (ARM64)
+curl -fsSL https://github.com/Shoplazza/shoplazza-cli/releases/latest/download/shoplazza-cli-linux-arm64.tar.gz | tar -xz
+sudo install -m755 shoplazza /usr/local/bin/
 ```
 
-> Use `shoplazza theme publish` to select and publish an unpublished theme from your theme library. If you want to publish your local theme, then you need to run `shoplazza theme push` first.
-
-### Find your theme ID
-
-```terminal
-$ shoplazza theme list
-```
-
-> You might want to use a theme's ID to pull, push, publish, or delete a theme using Shoplazza CLI.
-
-
+</details>
 
-## Theme Extension Develop
+<details>
+<summary>Build from source</summary>
 
-### Overview
-
-Theme Extension is a method provided by Shoplazza for extending and customizing themes. Developers can use Theme Extensions to enhance and tailor theme pages.
-
-### Create an Extension
+Requires Go `v1.24`+. Installs to `~/.local/bin` (no `sudo` needed):
 
 ```bash
-shoplazza te create  
+git clone https://github.com/Shoplazza/shoplazza-cli.git
+cd shoplazza-cli
+make install
 ```
 
-When creating a new Theme Extension, you will be prompted to choose between two types: **Basic Extension** and **Embed Extension**.
-
-- **Basic Extension**: Allows modifying insertion positions via the theme editor.
-- **Embed Extension**: Insertion positions are hard-coded within the Extension.
+> If `~/.local/bin` is not on your `PATH`, add it: `export PATH="$HOME/.local/bin:$PATH"`.
+> For a system-wide install: `sudo make install PREFIX=/usr/local`.
 
-### Start Development
-
-```bash
-cd your-project  # Navigate to the project directory
-shoplazza te serve  
-```
+</details>
 
-Since the Extension is displayed on theme pages, so you need to select a theme for preview. A preview link will be provided after selection.
+### Quick Start (Human Users)
 
-- **First link**: Redirects to the theme editor. You can add the Extension to theme pages here. After adding, save the changes to preview on the client side.
-- **Second link**: Redirects to the storefront preview page. After adding the Extension via the editor, any local code updates will take effect upon refreshing the storefront page.
-
-### Build for Production
+> **Note for AI assistants:** If you are an AI Agent helping the user install, jump directly to [Quick Start (AI Agent)](#quick-start-ai-agent).
 
 ```bash
-shoplazza te build  
-```
-
-Generates a deployable production build from the current project code. Multiple builds can be created, and one can be selected during deployment.
+# Log in (replace with your store domain)
+shoplazza auth login --store-domain my-store.shoplazza.com --domain products,orders
 
-### Deploy an Extension
+# Verify
+shoplazza auth status
 
-To deploy an Extension to your store:
-
-```bash
-shoplazza te deploy  
+# Start using
+shoplazza products list --format table
 ```
 
-Once deployed, the Extension will be live in the store.
-
-### Connect Extension to an APP
+### Quick Start (AI Agent)
 
-An APP is the primary extension method of Shoplazza platform. A Theme Extension is part of an APP, and one APP can connect multiple Theme Extensions. To conect your Extension to an APP:
+> Run the login command, extract the authorization URL from output, and send it to the user. The command polls until the user completes OAuth in their browser.
 
 ```bash
-shoplazza te connect
+npm install -g shoplazza-cli
+shoplazza auth login --store-domain <store-domain> --domain products,orders
+shoplazza auth status
 ```
 
-You will be prompted to enter the APP's `client_id` and `client_secret`, which can be obtained from the Shoplazza Partner Dashboard.
+## Authentication
 
-### Release an Extension
-To update the Extension version connected to your app, run the release command:
+| Command | Description |
+|---------|-------------|
+| `auth login` | Account-only OAuth — opens browser, obtains UAT |
+| `auth login --store-domain <domain>` | OAuth + store token (requires `--scope` or `--domain`) |
+| `auth store use --store-domain <domain>` | Switch current store |
+| `auth logout` | Sign out and remove credentials |
+| `auth status` | Show current auth state |
+| `auth scopes` | List available and granted scopes |
 
 ```bash
-shoplazza te release  
-```
-
-The release will be based on the current production version of your store. Once published, the changes will take effect for **all stores that have installed your app**.
-
-### CLI Command Guide
+# Interactive login with store
+shoplazza auth login --store-domain my-store.myshoplazza.com --domain products
 
-|                Command                |                  Description                   |
-| :-----------------------------------: | :--------------------------------------------: |
-|         `shoplazza te create`         |      Create a new Theme Extension project      |
-|         `shoplazza te serve`          |        Start a local development server        |
-|         `shoplazza te build`          |  Build a production version of the Extension   |
-|        `shoplazza te versions`        |  View production version list of an Extension  |
-|          `shoplazza te list`          |      List private Extensions in the store      |
-|         `shoplazza te deploy`         | Deploy a production build to the current store |
-| `shoplazza te connect <extension-id>` |          Bind an Extension to an APP           |
-|        `shoplazza te release`         |     Publish an Extension to its bound APP      |
+# UAT fast-path (non-interactive, for CI)
+shoplazza auth login --uat <user-access-token>
 
-## Core commands
+# Switch store
+shoplazza auth store use --store-domain another-store.myshoplazza.com
 
-### help
-
-```terminal
-$ shoplazza help
+# Check status
+shoplazza auth status
 ```
 
-> Lists the available commands and describes what they do.
-
-### login
+Access tokens are stored in the OS-native keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service).
 
-```terminal
-$ shoplazza login --store developer.myshoplaza.com
+## Development Workflows
 
-$ shoplazza login --partner
-```
+### App Development
 
-> --store: Authenticates and logs you into the specified store with Shoplazza CLI.
-> --partner: Authenticates and logs you into the partner with Shoplazza CLI.
+The CLI covers the full app lifecycle: create, configure, develop, and deploy.
 
-### logout
-
-```terminal
-$ shoplazza logout
-
-$ shoplazza logout --partner
-```
+```bash
+# 1. Create a new app project (creates a sub-directory)
+shoplazza app init --name "My App" --partner <partner-id>
 
-> Default to logout your store, logs you out of the Shoplazza account and store, the logout command clears credentials. You need to reauthenticate the next time that you connect to a store.
-> --partner: Clear your partner info, and you need to reauthenticate the next time.
+# 2. Add extensions (theme / checkout / function)
+cd my-app
+shoplazza app extension create --type checkout --name my-checkout
+shoplazza app extension create --type theme --name my-theme --theme-type basic
+shoplazza app extension create --type function --name my-fn
 
+# 3. Local development (dev server + HMR) — store comes from the active app config
+shoplazza app dev
 
-### switch
+# 4. Deploy all extensions
+shoplazza app deploy
 
-```terminal
-$ shoplazza switch --store developer.myshoplaza.com
+# 5. View deployed versions
+shoplazza app versions
 ```
 
-> Switches between stores without logging out and logging in again.
+<details>
+<summary>Additional app commands</summary>
 
-### store
+```bash
+shoplazza app list                              # List apps in your account
+shoplazza app info                              # Print app and extension info
+shoplazza app config use --config alt.toml      # Switch active app config
+shoplazza app config link --client-id <id>      # Link an existing app
 
-```terminal
-$ shoplazza store
+# Function extensions (compile/release individually)
+shoplazza app function compile --extension my-fn
+shoplazza app function release --extension my-fn
+shoplazza app function list
 ```
 
-> Displays the store that you're currently connected to.
+</details>
 
-### version
+### Theme Development
 
-```terminal
-$ shoplazza version
-```
+The CLI provides a complete theme development workflow with live reload.
 
-> Displays the version of Shoplazza CLI that you're running.
+```bash
+# 1. Scaffold a new theme from the Nova-2023 template
+shoplazza themes init --name my-theme
 
-## Theme commands
+# 2. Start the dev server (auto-creates a development theme, live reload)
+cd my-theme
+shoplazza themes serve
 
-### init
+# 3. Pull / push / package
+shoplazza themes pull --theme-id <theme-id>
+shoplazza themes push --theme-id <theme-id>
+shoplazza themes package
 
-```terminal
-$ shoplazza theme init [--name]
+# 4. Upload as a preview
+shoplazza themes share
 ```
 
-> Clones a Git repository to your local machine to use as the starting point for building a theme.
-
-### serve
+## Three-Layer Command System
 
-```terminal
-$ shoplazza theme serve [--theme]
-```
+The CLI provides three levels of granularity, covering everything from quick operations to fully custom API calls.
 
-> Uploads the current theme to the store that you're connected to, and returns the preview link.
+### 1. Shortcuts
 
-### list
+Prefixed with `+`, designed to be friendly for both humans and AI, with smart defaults and structured output.
 
-```terminal
-$ shoplazza theme list
-```
+```bash
+# Products
+shoplazza products +search --keyword "shirt"
+shoplazza products +publish <product-id>
 
-> Lists the themes in your store, along with their IDs and statuses.
+# Discounts — automatic
+shoplazza discounts +rebate --title "Summer Sale" --percentage 15 --min-amount 100
+shoplazza discounts +flashsale --title "Flash Sale" --percentage 20 --product-ids "123,456"
 
-### pull
+# Discounts — code-based
+shoplazza discounts +percent-code --code "SAVE20" --percentage 20
+shoplazza discounts +bxgy-code --code "BUY2GET1" --buy-quantity 2 --get-quantity 1
 
-```terminal
-$ shoplazza theme pull [--theme]
+# Orders
+shoplazza orders +ship <order-id>
 ```
 
-> Retrieves theme files from Shoplazza, if no theme is specified, then you're prompted to select the theme to pull from the list of the themes in your store.
+Run `shoplazza <domain> --help` to see all shortcuts for a domain.
 
-### push
+### 2. API Commands
 
-```terminal
-$ shoplazza theme push [--theme]
-```
+Auto-generated from OpenAPI metadata — commands mapped 1:1 to platform endpoints.
 
-> Uploads your local theme files to Shoplazza, overwriting the remote theme if specified, if no theme is specified, then you're prompted to select the theme to overwrite from the list of the themes in your store.
+```bash
+shoplazza products list
+shoplazza products get <product-id>
+shoplazza products create --data @product.json
 
-### share
+shoplazza discounts list
+shoplazza discounts create-discount --data @discount.json
 
-```terminal
-$ shoplazza theme share
+# All domains: products, discounts, orders, customers, billing, shop, themes, webhook
+shoplazza orders list
+shoplazza customers list
 ```
 
-> Uploads your theme as a new, unpublished theme in your theme library. The command return a preview link that you can share with others.
+### 3. Raw API Calls
 
-### publish
+Call any Shoplazza Open Platform endpoint directly for full coverage.
 
-```terminal
-$ shoplazza theme publish [--theme]
+```bash
+shoplazza api rest GET /openapi/2022-01/products.json
+shoplazza api rest POST /openapi/2022-01/products.json \
+  --data '{"product": {"title": "New Product", "status": "active"}}'
 ```
 
-> Publishes an unpublished theme from your theme library, if no theme ID is specified, then you're prompted to select the theme that you want to publish from the list of themes in your store.
+## Advanced Usage
 
-### package
+### Common Flags
 
-```terminal
-$ shoplazza theme package
-```
+| Flag | Scope | Description |
+|------|-------|-------------|
+| `--format json\|pretty\|table` | All commands | Output format (default: `json`) |
+| `--fields "f1,f2"` | Shortcut commands | Response field projection |
+| `--dry-run` | API & shortcut commands | Preview request without executing |
+| `--jq "expr"` / `-q` | API commands | Filter JSON output with jq expression |
 
-> Packages your local theme files into a ZIP file that can be uploaded to Shoplazza. The ZIP file uses the name theme_name-theme_version.zip, based on parameters in your `settings_schema.json` file.
+### Schema Introspection
 
-### delete
+Inspect any service's methods, parameters, required scopes, and response shape:
 
-```terminal
-$ shoplazza theme delete [--theme]
+```bash
+shoplazza schema                              # List all services
+shoplazza schema products                     # Inspect a service
+shoplazza schema products.list                # Inspect a method
 ```
 
-> Deletes a theme from your store, if no theme is specified, then you're prompted to select the theme that you want to delete from the list of themes in your store.
+### Environment Variables
 
-## app
+| Variable | Description |
+|----------|-------------|
+| `SHOPLAZZA_UAT` | User Access Token for non-interactive login (equivalent to `--uat`) |
+| `SHOPLAZZA_CLI_AUTH_BASE_URL` | Override auth base URL (default: `https://partners.shoplazza.com`) |
 
-### init
+## Security & Risk Warnings
 
-```terminal
-$ shoplazza app init
-```
+> Read Before Use
 
-> Initialize a new Shoplazza app project.
+- **AI Agent Automation Risk** — When AI Agents operate the CLI on your behalf, all API calls carry real consequences (creating products, modifying orders, deleting discounts). Always review the Agent's proposed commands before execution.
+- **Credential Safety** — Tokens are stored in the OS-native keychain. Never share your UAT or store tokens. Rotate credentials immediately if you suspect exposure.
+- **Scope Control** — Use `--scope` or `--domain` to limit the permissions granted during login. Grant only the scopes your workflow requires.
 
-### generate
+## Contributing
 
-```terminal
-$ shoplazza app generate extension
-```
+Contributions are welcome! If you find a bug or have a feature suggestion, please open an Issue or Pull Request on [GitHub](https://github.com/Shoplazza/shoplazza-cli).
 
-> create a new extension.
+For major changes, please open an issue first to discuss the approach.
 
-### dev
+### Local Setup
 
-```terminal
-$ shoplazza app dev
-```
+```bash
+# Build
+make build
 
-> choose a store to test your extension app.
+# Run tests
+make test
 
-### deploy
+# Lint (pre-PR)
+go mod tidy
+go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main
 
-```terminal
-$ shoplazza app deploy
+# Install locally
+make install
 ```
 
-> deploy your extension app.
-
-## Theme Directory
+Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`, `ci:`.
 
-You can run certain theme commands, such as shoplazza theme serve, only if the directory you're using matches the default Shoplazza theme directory structure. This structure represents a buildless theme, or a theme that has already gone through any necessary file transformations. If you use build tools to generate theme files, then you might need to run commands from the directory where the generated files are stored.
-
-The default Shoplazza theme directory structure is as follows:
-
-```terminal
-└── project
-    ├── assets
-    ├── config
-    ├── layout
-    ├── locales
-    ├── sections
-    ├── snippets
-    └── templates
-```
+## License
 
-## Support(OS Terminals)
-
-You should expect mostly good support for the CLI below. This does not mean we won't look at issues found on other command line - feel free to report any!
-
-- Mac OS
-  - Terminal.app
-  - iTerm
-- Windows (Known issues):
-  - ConEmu
-  - cmd.exe
-  - Powershell
-  - Cygwin
-- Linux (Ubuntu, openSUSE, Arch Linux, etc):
-  - gnome-terminal (Terminal GNOME)
-  - konsole
+This project is licensed under the **MIT License**.
+When running, it calls the Shoplazza Open Platform APIs. Usage of these APIs is subject to the [Shoplazza Developer Agreement](https://www.shoplazza.dev/).