@cerkel/cli 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,503 @@
-# Temporary Holding Version
+# @cerkel/cli — the `cerkel` CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run a Cerkel store from the terminal, by hand or with Claude Code: its **theme** as local
+files (preview it on the store's real domain and send it for approval), and its **catalogue** —
+products, prices, bundles, stock and collections (see [Store commands](#store-commands-catalogue-prices-stock-collections)).
+It works like Shopify CLI, with one difference: there is no theme publish, unpublish or rollback
+command. **`submit` sends the draft for approval; for
+the store owner's login it publishes immediately** (a rollback link is printed) — a login whose owner
+holds `themes.publish` in that store (owner, admin), and Cerkel team logins. Everyone else's request
+waits for the owner, who approves and publishes it in the Cerkel admin.
+
+Requires Node.js 20 or newer.
+
+## 1.0.1: published by GitHub, no npm token
+
+Same commands as 1.0.0. This is the first release that GitHub Actions publishes through npm trusted publishing
+(`publish-cli.yml`), so the package carries a provenance statement and no npm token exists anywhere.
+
+## 1.0.0: the CLI is now `cerkel`
+
+The package is **@cerkel/cli** and the command is **`cerkel`** (it was @raizn/cli and `raizn`).
+
+- **Install:** `npm rm -g @raizn/cli`, then `npm i -g @cerkel/cli`. Both packages install a `raizn` command,
+  so remove the old one first, or npm refuses the second.
+- **`raizn` still works for now.** It prints one line on stderr (`raizn is now cerkel …`) and then does exactly
+  what `cerkel` does, so old scripts keep running. It goes away in a later release.
+- **Variables:** `CERKEL_TOKEN` and `CERKEL_API_URL`. The old `RAIZN_TOKEN` and `RAIZN_API_URL` still work; when
+  both are set, the `CERKEL_` one wins.
+- **Your logins move by themselves.** The first command reads what `raizn` saved (keychain service `raizn-cli`, or
+  `~/.config/raizn/credentials`), saves it under `cerkel-cli` or `~/.config/cerkel/credentials`, and removes the old
+  copy. Nothing to do.
+- **Folders you already pulled keep working.** A new folder keeps its state in `.cerkel/`; one pulled by `raizn`
+  keeps using its `.raizn/` where it is. Page files written by `raizn` (`<!--raizn …-->`) still push; new pulls write
+  `<!--cerkel …-->`.
+- New logins appear in Settings → AI assistant connection (MCP) as "cerkel CLI — <computer> — <store>".
+
+## 0.3.0
+
+- **The default host is now admin.cerkel.ai** (`https://admin.cerkel.ai/api/mcp`). ecom.raizn.com keeps serving
+  the same admin and API.
+- **Run `cerkel login` again.** Logins are kept per host, so a login made on ecom.raizn.com is not used for
+  admin.cerkel.ai.
+- **A theme folder pulled from ecom.raizn.com keeps using it.** The folder's recorded API outranks
+  `CERKEL_API_URL` and the default, so its commands still go to ecom.raizn.com with that host's login.
+- **To keep the old host everywhere else**, set `CERKEL_API_URL=https://ecom.raizn.com/api/mcp`.
+
+## Install and log in
+
+```sh
+npm i -g @cerkel/cli                     # or run any command with npx @cerkel/cli …
+cerkel login --store justloofah-jo       # opens the browser: sign in, check the store, press Allow, done
+```
+
+**A login is for one store.** It reaches exactly the store you chose and nothing else: `cerkel
+stores` and `cerkel whoami` show that one store, and a command for any other store is refused
+without naming it. To work on another store, log in to that one too
+(`cerkel login --store nahleh-jo`). Your other logins are kept, so a Cerkel-team member who works on
+several stores logs in once per store and then just works: each theme folder uses the login of its
+own store. Switching store means using that store's login (or its folder), never widening one.
+
+Like Shopify CLI, the package is public and holds no secrets. Everything is decided by the server:
+what you can do follows your staff role and stores in the Cerkel admin, on every call. Removing
+someone in Settings → Staff cuts their CLI off on the next command.
+
+`cerkel login` opens `/cli/authorize` on admin.cerkel.ai (or on the host the command uses: `--api`, the folder's
+recorded API, or `CERKEL_API_URL`). You sign in as usual (WhatsApp code or
+password + authenticator), pick the store (only stores where you can edit themes are listed;
+`--store` pre-selects it, and inside a theme folder `cerkel login` means the folder's store) and press
+**Allow**. The browser then hands a one-time code back to `cerkel` on this computer (127.0.0.1 only),
+and `cerkel` trades it for your token. The code is useless to anyone else, because it needs a secret
+that never leaves this process (PKCE). The token lasts 90 days and appears in Settings → AI
+assistant connection (MCP) as "cerkel CLI — <computer> — <store>" (logins made before 1.0 keep their "raizn CLI — …" name), where you can revoke it.
+
+**Logins from raizn 0.1.x** reached every store. The server no longer accepts them: the first command
+says `This login is not tied to a store any more — run cerkel login --store <slug>` (naming the
+folder's store when you are in one), forgets that login, and `cerkel login --store <slug>` makes a
+proper one. A one-store token you once pasted with `cerkel login --token` keeps working: it is filed
+under its store the first time you use it.
+
+**macOS: `EACCES: permission denied` on `npm i -g`.** Node's installer makes the global folder
+belong to the system. Don't use `sudo`. Either run commands through `npx @cerkel/cli …`, or point
+npm's global folder at your home directory once:
+
+```sh
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
+npm i -g @cerkel/cli
+```
+
+No browser on this machine (a server over SSH)? Create a token for one store by hand in that
+Settings page and run `cerkel login --token`, or pipe it in with `echo "$TOKEN" | cerkel login`. A token
+that is not tied to exactly one store is refused and not saved.
+
+**Releasing a new version** (maintainers): bump `version` in `packages/cli/package.json` in a PR,
+merge it, then run the **Publish cerkel CLI** workflow (GitHub → Actions). There is no npm token to
+manage: npm trusts that workflow in this repo directly (trusted publishing, set on npmjs.com →
+`@cerkel/cli` → Settings).
+
+Either way, `login` checks the token with the server before saving it, and prints who you are, the
+one store it is for and its permissions. A token the server rejects is not saved.
+
+Logins are stored in your OS keychain (service `cerkel-cli`, account = the API origin; the entry holds
+one token per store). If there is no keychain, they go to `~/.config/cerkel/credentials`
+(`%APPDATA%\cerkel\credentials` on Windows) with `0600` permissions.
+
+```sh
+cerkel logins                      # your own logins on this computer, one per store, each checked with the server
+cerkel logout                      # inside a theme folder: that store's login; with one login: that one
+cerkel logout --store nahleh-jo    # one store's login
+cerkel logout --all                # every login for this API
+```
+
+Which login a command uses: the theme folder's store (`.cerkel/state.json`), else `--store <slug>`,
+else your only login. With several logins and no folder or `--store`, the command stops and asks you
+to pass `--store`; it does not list your stores (`cerkel logins` does, on purpose — that data is on
+your own disk). `cerkel logout` only forgets a login on this computer; revoke the token itself in
+Settings → MCP.
+
+
+## Workflow
+
+```sh
+cerkel login --store nahleh                # once per store
+cerkel stores                              # the store this login is for
+cerkel theme list --store nahleh           # live + draft themes
+mkdir nahleh-theme && cd nahleh-theme
+cerkel theme pull --store nahleh           # newest draft (offers to create one from live if none)
+cerkel theme dev                           # push on save + preview link on the real store domain
+cerkel theme check                         # validate changed files (nothing saved)
+cerkel theme submit -m "Ramadan homepage"  # send for approval; prints the admin link
+```
+
+- **pull** downloads a draft into the current folder (or `--dir`). Use `--theme <id>` to choose a
+  specific draft. If the store has no draft, `pull` asks whether to create one from the live theme
+  (`--yes` answers for you, and scripts must pass it). If you have local changes, `pull` refuses
+  unless you pass `--force`. A folder holds one store's theme: pulling another store into it is
+  refused, so pull it into a folder of its own (`--dir`). Without `--store` outside a folder, `pull`
+  uses the store of your only login.
+- **dev** pushes pending changes first, then watches the folder. A burst of saves goes to the server
+  as one request, about a second after you stop typing. Errors show inline as
+  `path:line:col message`. It prints a signed preview link and fetches a fresh one before the
+  30-minute link expires. **Open each new link:** a tab still using the old one stops showing the
+  draft and quietly falls back to the live site after 30 minutes. Ctrl-C stops it.
+- **push** uploads only the files you changed since the last pull or push. If someone else changed
+  a file on the server in the meantime (a teammate, or the admin editor), `push` refuses that file,
+  prints a diff (server vs yours) and exits 1. Merge the changes and push again, or use `--force`
+  to overwrite the server's copy. `--force` first lists each conflicting file with how many server
+  lines not in your file would be lost, and asks `y/N`. `--yes` answers for you, and scripts must
+  pass it: without a terminal, `--force` alone refuses. If the server's copy changes again while
+  you are answering, that file is refused as a new conflict instead of being overwritten.
+- **preview** prints the signed preview link, and `--open` opens it in your browser.
+- **submit** refuses while you have unpushed changes. For the **store's owner or an admin** (the
+  login carries `themes.publish` and its owner holds it in that store right now) and for **Cerkel's own
+  team** (a @raizn.net / @raizn.com email) the server approves
+  and publishes it in the same step: `submit` says the change is **LIVE** and prints the request link,
+  where Rollback is one click. Everyone else's request waits for someone with publish rights. It prints the request id and
+  `https://admin.cerkel.ai/themes/requests/<id>` (on the host the folder uses).
+
+### More theme commands (Shopify CLI parity)
+
+```sh
+cerkel theme info                          # this folder's draft (or --theme <id>, or the live theme)
+cerkel theme open                          # the admin's visual editor (--code: the code editor, --print: only the link)
+cerkel theme rename "Ramadan 2027"         # this folder's draft, or --theme <id>
+cerkel theme delete --theme <id>           # a DRAFT; type its name to confirm (--yes in scripts)
+cerkel theme share --days 7                # a preview link for someone else, on the store's own domain (1–14 days)
+cerkel theme console --path /products/x    # Liquid against the store's real data: product.title, collections | size …
+cerkel theme console -e "shop.name"        # one shot (or pipe Liquid in)
+cerkel theme profile --path / --runs 3     # each section's server render time, slowest marked
+cerkel theme package                       # zip this folder's theme files (-o file.zip)
+cerkel theme init my-theme                 # a new folder from a starter theme (--list shows them)
+cd my-theme && cerkel theme push --new     # → a NEW draft (copied from live) with these files; the folder becomes its checkout
+```
+
+- **console** evaluates on the store's own storefront with the objects a section on `--path` gets, in
+  the theme of this folder (else the live one). Inside: `.path /collections/x`, `.locale en`, `.help`,
+  `.exit` (or Ctrl-D). It only reads.
+- **profile** renders the page exactly as a shopper gets it, but section by section, and prints the
+  server time of each with what rendered it (a theme file, a built-in section) and any Liquid error.
+- **share** links show the draft as it is on the server: push first. Deleting the draft revokes them.
+- **delete --theme** never deletes the live theme or a draft waiting for review.
+
+### Example: Just Loofah
+
+Every Just Loofah page is a store like Nahleh's — same file layout, same commands:
+
+```sh
+cerkel theme pull --store justloofah-jo
+#   templates/index.json         templates/product.json       templates/page.products.json
+#   templates/page.habit.json    templates/404.json
+#   layout/header.json           layout/footer.json
+#   config/settings.json         assets/custom.css
+#   locales/ar.json              locales/en.json
+```
+
+Text settings are **localized**: one setting holds every language as an object, never a bare string.
+Editing `templates/index.json`'s loyalty section:
+
+```diff
+   { "id": "loyalty", "type": "jl-loyalty", "settings": {
+     "label": { "ar": "مكافأة الولاء", "en": "Loyalty reward" },
+-    "headline": { "ar": "اطلب مرّة… ووفّر للأبد", "en": "Order once. Save forever." },
++    "headline": { "ar": "اطلب مرّة… ووفّر للأبد", "en": "Order once, save forever." },
+     "body": { "ar": "…", "en": "…" }
+   } }
+```
+
+`cerkel theme push` validates and saves it to the draft; `cerkel theme dev` gives a live preview on the
+store's own domain while you edit. If the store has never been seeded (no rows to pull), the admin's
+Settings → Data sources → "تهيئة قالب Just Loofah" button (or re-running "استيراد باقات وإضافات Just
+Loofah") creates them first — content identical to the built-in fallback, so nothing changes visually
+until you edit something.
+
+### Built-in texts: `locales/<lang>.json`
+
+The storefront's own texts — "Add to cart", cart and checkout labels, the account and tracking
+pages, search, the default policies, a Just Loofah theme's SEO title and WhatsApp prefill — are one
+file per store language (Kurdish too, when the store sells in it). `pull` writes every text the
+language shows: the theme's own wording where it has one, the default everywhere else.
+
+```json
+{
+  "platform": { "addToCart": "Add to cart", "trackTitle": "Track your order", "…": "…" },
+  "theme":    { "product.addToCart": "Add to Cart", "whatsapp.prefill": "Hi, I have a question about Just Loofah products 🌿", "…": "…" }
+}
+```
+
+`platform` holds the texts every theme shares; `theme` holds the theme's own (only a theme whose
+preset has its own dictionary, today Just Loofah). Change a value and `push`: only texts that differ
+from the default are stored, a line you delete goes back to its default, and a file that names an
+unknown key, drops or adds a `{placeholder}`, or contains HTML is refused with the line. Kurdish
+files leave out the texts nobody has translated yet (the store shows Arabic there); add the line to
+translate one. Merchants edit the same texts in the admin: Themes → ⋯ → Edit theme content.
+
+### Sections, blocks and snippets: new kinds of section with no deploy
+
+A section is ONE file, `sections/<type>.liquid`: its Liquid, then `{% stylesheet %}`, then
+`{% schema %}` (docs/liquid-themes.md §2). It belongs to the **theme** you pulled, like its templates:
+it goes live when that draft is approved and published, and a rollback brings the previous files back.
+
+```sh
+cerkel section new promo-strip --starter blank   # writes sections/promo-strip.liquid locally
+cerkel section duplicate promo-strip promo-v2    # a copy to redesign side by side ("(copy)" in its name)
+cerkel theme push                                # adds them to the draft (or keep `cerkel theme dev` running)
+cerkel section history promo-strip               # every save in every theme of the store, newest first
+cerkel section restore promo-strip 3             # the old file becomes a NEW version; history kept
+cerkel section delete promo-strip                # refused while one of the draft's templates places it
+```
+
+Then place the section with the admin's visual editor (or in `templates/*.json`) and
+`cerkel theme submit -m "…"`. A file `sections/<type>.liquid` whose type is a built-in section (e.g.
+`jl-hero-video`) REPLACES that built-in section in this theme only — that is how a section is
+redesigned one at a time.
+
+`blocks/<name>.liquid`, `snippets/<name>.liquid` and `assets/<name>.css|svg` are theme files too:
+pull, push, dev, `cerkel theme history <file>`, `cerkel theme restore <file> <version>` and
+`cerkel theme delete <file…>` work on every one of them. `assets/*.generated.css` is written by Cerkel
+from the theme's files: pulled for reference, never pushed. JavaScript files are not theme files —
+interactivity comes from the platform's components (docs/liquid-themes.md §7).
+
+**Upgrading from CLI 0.1.** Sections used to be three files (`.liquid`, `.schema.json`, `.css`). In an
+old checkout, `push` refuses and says so; `cerkel theme pull` writes the one-file sections and removes
+the old side files you did not change (an edited one is kept — move its content into the
+`{% schema %}` / `{% stylesheet %}` of the `.liquid` file, then delete it).
+
+## Orders, customers and reviews
+
+Every command runs against your login's store (or `--store <slug>`) and takes `--json`. Writes show
+the server's change first and ask (`--yes` in scripts, `--dry-run` to only look); the server applies
+the admin's rules and its refusal is printed as is.
+
+```bash
+cerkel order list --status new,confirming            # the confirmation queue's orders
+cerkel order get JL-1001                             # items, totals, customer, courier, timeline, next steps
+cerkel order transition JL-1001 confirmed            # confirming / unreachable / cancelled (--note) / delivered …
+cerkel order call JL-1001 no_answer                  # logs the call, schedules the next one
+cerkel order hold JL-1001 --reason customer_later --until 2026-10-20
+cerkel order release JL-1001
+cerkel order note JL-1001 Customer asked for an evening delivery
+cerkel order tag JL-1001 --add gift --remove old
+cerkel order edit JL-1001 --qty JL-90=3 --add JL-SOAP=1 --reason "Customer called"   # --dry-run to preview
+cerkel draft create --name Laila --phone 0791234567 --governorate JO-AM --address "Street 7" --item JL-90=2
+cerkel draft complete <draft id>                     # places the order (number, stock, COD checks)
+cerkel customer get JL-1001                          # by phone or by any of their orders
+cerkel customer flag 0791234567 blocked --note "Fake orders"     # --off lifts it
+cerkel customer update JL-1001 --name "Laila Haddad" --note "Prefers evenings"
+cerkel review list --status pending
+cerkel review moderate <review id> approved
+cerkel review reply <review id> Thank you for your order!
+```
+
+An order the courier already has takes no new items, and editing it needs an admin's approval:
+`cerkel order edit` always submits the edit for approval (`--reason` required) — from any login, an
+admin's included — and nothing changes until an admin approves it in the admin. Phones are masked unless your login may see
+customer details.
+
+## Folder layout
+
+```
+templates/index.json            templates/<name>.json (product, product.<suffix>, collection…, page…, …)
+layout/header.json              layout/footer.json
+config/settings.json            theme settings (merged on write: deleting a key does not remove it)
+assets/custom.css               the theme's custom CSS
+locales/<ar|en|ckb>.json        the theme's built-in texts per language (the whole language: a deleted line goes back to its default)
+sections/<type>.liquid          a section: Liquid + {% stylesheet %} + {% schema %}, one file
+blocks/<name>.liquid            a theme block (Horizon-style; `_name` = private)
+snippets/<name>.liquid          a snippet for {% render %}
+assets/<name>.css|svg           plain CSS (loaded on every page of the theme) and sanitised SVG
+assets/<name>.generated.css     written by Cerkel (read-only)
+.cerkel/state.json               what was pulled: api, store, theme, and each file's server tag + local hash
+.cerkel/.gitignore               "*", so .cerkel never lands in git (a folder pulled before 1.0 keeps its .raizn/)
+```
+
+Anything else in the folder, such as a README or a `.git` directory, is ignored. Files are written
+exactly as the server sends them, so Arabic text round-trips byte for byte. A git checkout with
+`core.autocrlf` does not count as modified, because line endings are normalised to LF before
+comparing and sending. A leading UTF-8 BOM (Windows PowerShell 5.1 `Set-Content -Encoding utf8`
+adds one) is dropped before comparing and sending, so a file that differs only by a BOM is not a
+change. A section, block, snippet or asset file you delete locally is deleted from the draft on the
+next `push` or by `dev` — only if the server still holds the copy you last synced, and after the
+templates in the same push (so a template can stop placing a section and the section can go in one
+push). `--nodelete` keeps them. Templates, layout, settings and `assets/custom.css` are never deleted.
+
+A read-only reference copy of the **live** theme can be pulled into its own folder:
+
+```sh
+cerkel theme pull --store nahleh --live --dir ../nahleh-live
+```
+
+`push`, `dev`, `submit` and the section write commands refuse to run in that folder. The live theme
+is never pulled for editing.
+
+## Store commands (catalogue, prices, stock, collections)
+
+Each command is one MCP tool (`docs/mcp.md`, phase A); the server decides permission, store and
+money rules and its refusal is printed verbatim. The store is your login's store (or `--store`).
+
+**Every write shows the change and asks first.** It sends a dry run, prints the server's diff, asks
+`Apply this change to <store>? [y/N]`, and only then applies. `--yes` answers for you, `--dry-run`
+stops after the diff, `--json` prints the server's answer. Without a terminal (scripts, CI) a write
+needs `--yes` and is refused before anything is sent.
+
+```sh
+cerkel store info                                   # currency (decimals, cash step), languages, domains, COD policy
+cerkel price set JL-90 18.000                       # shows "price: 15.000 JOD → 18.000 JOD", asks, applies
+cerkel price set JL-90 - --compare-at none          # "-" keeps the price; none removes the compare-at price
+cerkel price import prices.csv --dry-run            # sku,price,compare_at,cost — all or nothing, bad rows listed
+cerkel product list rose --low                      # search; --status, --collection, --category, --published|--hidden
+cerkel product get loofah-90                        # variants with this store's prices and stock
+cerkel product create --title "en:Rose soap" --title "ar:صابون الورد" --price 4.500 --sku JL-ROSE --quantity 12
+cerkel product update rose-soap --tags soap,rose --category skin/soap --field scent=rose
+cerkel product status active rose-soap body-soap    # one or many
+cerkel product publish rose-soap                    # show it in THIS store (unpublish hides it)
+cerkel product duplicate rose-soap
+cerkel variant options knee --option "Size=S,M,L" --lang en --create-variants
+cerkel variant add knee --option Size=L --sku KS-L
+cerkel image add loofah-90 https://…/a.jpg          # or a media library id; image remove / image reorder
+cerkel category set rose-soap skin/soap
+cerkel offer set loofah-90 --label "en:5 + 1" --price 15.000 --line JL-SQ:5 --line JL-CYL:1
+cerkel offer set loofah-90 deal-6 --inactive        # change an existing tier by its key
+cerkel addon set loofah-90 JL-SOAP --price 0        # a free gift with the order
+cerkel inventory get loofah-90                      # on hand / reserved / available per location
+cerkel inventory adjust JL-SQ +24 --reason received # or -2 --reason damage; reasons: correction, damage, theft, received, return, count
+cerkel inventory set JL-SQ 40                       # an exact count
+cerkel inventory tracking loofah-90 --track on --continue-selling off
+cerkel inventory low
+cerkel collection create --title "en:Loofahs" --product square-loofah --product loofah-90
+cerkel collection reorder loofahs loofah-90         # listed first, the rest after
+cerkel collection unpublish loofahs
+```
+
+Amounts are typed in the store's currency exactly as you would write them — `18.000` or `18`
+(JOD, 3 decimals), `12500` (IQD, steps of 250) — and parsed by the server; too many decimals or an
+off-step IQD amount is refused, never rounded. Text flags take `en:Text` / `ar:نص` (repeat per
+language) or plain text in `--lang` (default `ar`). `cerkel <command> --help` lists every flag.
+
+| Group | Commands | Needs (in the admin) |
+|---|---|---|
+| `store` | `info` | any login |
+| `product` | `list`, `get`, `create`, `update`, `status`, `publish`, `unpublish`, `duplicate` | view / edit products |
+| `variant`, `image`, `category` | `set`, `add`, `delete`, `options` · `add`, `remove`, `reorder` · `list`, `set` | edit products |
+| `price` | `set`, `import` | edit products |
+| `offer`, `addon` | `list`, `set`, `delete` · `set`, `delete` | edit products + manage offers |
+| `inventory` | `get`, `locations`, `low` · `adjust`, `set`, `tracking` | view stock · adjust stock |
+| `collection` | `list`, `get` · `create`, `update`, `add`, `remove`, `reorder`, `publish`, `unpublish` | view products · manage content |
+## Store commands: content, discounts, delivery, reports
+
+Every command acts on your login's store (or `--store <slug>`), prints a table (`--json` for
+everything), and a command that changes something **shows the server's diff and asks first**:
+`--yes` applies without asking (required in scripts), `--dry-run` only shows it. Amounts are in the
+store's currency, as you would write them: `2.000` (JOD), `5000` (IQD, steps of 250).
+
+```sh
+# Pages, policies and blog articles as files — like theme files
+cerkel page pull --store justloofah-jo     # pages/*.html, policies/*.html, blogs/<blog>/*.html
+$EDITOR policies/refund-policy.html       # settings in <!--cerkel {…} -->, bodies after <!--lang:ar--> / <!--lang:en-->
+cerkel page push                           # only changed files; a page changed in the admin meanwhile is a conflict
+cerkel page list --kind policy
+cerkel page delete /pages/old-offer
+
+cerkel menu pull && cerkel menu push        # menus/<handle>.json — { "title", "items": [ … ] }
+
+cerkel redirect add /old-offer /collections/all          # --temporary for 302
+cerkel redirect import redirects.csv                     # from,to[,301|302] per line
+cerkel redirect list --sort hits
+
+cerkel file upload https://example.com/hero.jpg          # copied into the media library; prints its URL
+cerkel file list --kind image
+
+cerkel promo create EID10 --percent 10 --expires 2026-10-31 --once
+cerkel promo create SHIP --free-delivery --min 20
+cerkel promo deactivate EID10
+
+cerkel zone list
+cerkel zone set --name-ar "إربد" --name-en Irbid --governorates JO-IR --fee 3.000 --eta 2
+cerkel zone set <zone-id> --fee 2.500
+
+cerkel report sales --since 2026-10-01 --until 2026-10-07 [--grain week] [--compare] [--csv]
+cerkel report products|governorates|funnel|couriers|customers|discounts|growth
+cerkel report live                          # visitors right now
+```
+
+**`cerkel call <tool> --args '{…}' [--allow-writes]`** calls any MCP tool with JSON arguments, like
+`shopify store execute`. It is read-only by default: a tool the server marks as a write is refused
+unless you pass `--allow-writes` (add `"dry_run": true` to see the change first). `cerkel call --list`
+shows every tool and whether it reads or writes.
+
+Reports need the reports permission; growth/ROAS and courier cash need finance access, `--csv` the
+download permission, and customer phone numbers the permission to see them — exactly as in the admin.
+
+**`cerkel whatsapp test <template> --to <+962…> [--values "v1|v2|…"] [--language ar]`** sends one approved
+WhatsApp template from the store's number to a phone, with the values in `{{1}}, {{2}}…` order separated
+by `|` — to try a template before customers get it. No order and no mapping are needed, and the store's
+"Enable sending" switch does not apply; the store's token never leaves the server. It prints WhatsApp's
+message id, or its error code (132001 = no such template in that language, 132000 = wrong number of
+values). Needs the WhatsApp scope (`whatsapp.templates.manage`). A tap on the test message's buttons moves
+no order (since 14 Oct 2026). Review buttons still rate that phone's latest real review request (72 h), so
+tap those only from a phone with no recent order.
+
+```sh
+cerkel whatsapp test raizn_confirmation_request --to +962780095281 --store justloofah \
+  --values "Qutiba|JL-TEST|13.000 د.أ|لوفة اسطوانية × 2"
+```
+
+## What this can never do
+
+- Publish, unpublish or roll back a theme or a section with a command of its own. `cerkel theme
+  publish` explains that publishing happens in the admin after approval, or, for the store owner's
+  login and Cerkel team logins, immediately on `submit` (which prints the rollback link).
+- Write to the live theme. The server refuses it (`not_a_draft`); that is the real check. As a
+  convenience, the CLI also refuses before sending anything when the folder's `.cerkel/state.json`
+  says it holds the live theme or anything other than a draft.
+- Reach staff, roles or tokens, payments, refunds or courier cash, open or pause a store, delete an
+  order, or take an order to the courier (`dispatched`). The store commands below cover the catalogue,
+  prices, stock and collections, pages and menus, redirects, files, promo codes, delivery zones and
+  reports, and orders, customers and reviews — in the login's own store,
+  within what you may do there in the admin.
+- Talk to any host but the configured API. `*.vercel.app` is refused (Jordanian ISPs reset those
+  connections), and plain `http` is only allowed for `localhost`.
+
+The server authorises every call. The CLI's own checks are there for convenience, and when the
+server refuses (`permission_denied`, `not_a_draft`, …), its message is shown verbatim. Two refusals
+are about which login you used, and are said in one line instead, naming only this login's store and
+the store you asked for: `This login is for X — run cerkel login --store Y` (`store_not_allowed`), and
+`This login is not tied to a store any more — run cerkel login --store <slug>` (a 0.1.x login). A 401
+(revoked or expired token) is never retried. On a 429, the CLI prints when you can retry: `dev` waits
+it out and keeps your queued changes, and other commands exit 1.
+
+## CI
+
+```yaml
+- run: npx @cerkel/cli theme check --store nahleh
+  env:
+    CERKEL_TOKEN: ${{ secrets.CERKEL_TOKEN }}
+```
+
+When `CERKEL_TOKEN` is set, it is used instead of any stored login and is never saved. Create it in
+Settings → MCP for the one store the pipeline checks. Without a `.cerkel/state.json`, `theme check
+--store <slug>` validates every theme file in the folder. It exits 1 on any error; warnings alone
+exit 0.
+
+## Options
+
+| | |
+|---|---|
+| `--api <url>` / `CERKEL_API_URL` | API endpoint. The default is `https://admin.cerkel.ai/api/mcp` (ecom.raizn.com still serves). The URL a folder was pulled from is recorded in its state, and later commands in that folder reuse it. |
+| `--store <slug>` | Which store's login to use (`login`, `logout`, `whoami`, `stores`, `theme list`, `theme pull`, `theme check`). Inside a theme folder the folder's store is used. |
+| `CERKEL_TOKEN` | Token for CI (one store); takes precedence over every stored login. |
+| `cerkel <command> --help` | Help for any command. |
+
+The token is never printed, logged or written to project files. Every line the CLI prints passes
+through a redactor.
+
+## Development
+
+```sh
+pnpm --filter @cerkel/cli build       # tsc → dist/, bin = dist/bin.js
+pnpm --filter @cerkel/cli test        # vitest, against a mocked endpoint (no network, no keychain)
+node packages/cli/dist/bin.js --help
+```
+
+The wire contract with the server is in `docs/theme-cli/contract.md`.

package/dist/api-url.js

@@ -0,0 +1,42 @@
+/** Where the CLI is allowed to send a token, decided once, before any request is built. */
+export const DEFAULT_API_URL = "https://admin.cerkel.ai/api/mcp";
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
+export class ApiUrlError extends Error {
+    name = "ApiUrlError";
+}
+/**
+ * Parse and vet an API URL. Refuses:
+ * - `*.vercel.app` — Jordanian ISPs reset any connection whose SNI or Host names it, so the
+ *   command would hang or fail in the market we serve; custom domains only.
+ * - plain http anywhere but loopback — the token rides in a header and must not cross a network
+ *   in clear text. Loopback http is allowed for local development against `pnpm dev:admin`.
+ * - credentials embedded in the URL, which would be sent alongside (and logged with) the request.
+ */
+export function parseApiUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        throw new ApiUrlError(`"${raw}" is not a valid URL. Expected something like ${DEFAULT_API_URL}.`);
+    }
+    const host = url.hostname.toLowerCase().replace(/\.$/, "");
+    if (host === "vercel.app" || host.endsWith(".vercel.app")) {
+        throw new ApiUrlError(`Refusing ${url.origin}: *.vercel.app addresses are blocked by Jordanian ISPs. Use the store platform's custom domain (default ${DEFAULT_API_URL}).`);
+    }
+    if (url.username || url.password) {
+        throw new ApiUrlError("Refusing an API URL with a username or password in it. Use `cerkel login` for the token.");
+    }
+    if (url.protocol === "http:") {
+        if (!LOOPBACK.has(host)) {
+            throw new ApiUrlError(`Refusing ${url.origin}: the API must use https (plain http is only allowed for localhost).`);
+        }
+    }
+    else if (url.protocol !== "https:") {
+        throw new ApiUrlError(`Refusing ${url.protocol} URL: the API must use https.`);
+    }
+    url.hash = "";
+    return url;
+}
+/** Credentials are keyed by origin so `/api/mcp` vs `/api/mcp/` never splits one login in two. */
+export const apiOrigin = (url) => url.origin;

package/dist/api.js

@@ -0,0 +1,48 @@
+import { ServerError } from "./errors.js";
+/**
+ * The one store a token is for, or null when it is not tied to exactly one (an old token that
+ * still reaches several stores, or none right now). Works with servers from before `store` existed.
+ */
+export function oneStoreOf(r) {
+    if (r.store && typeof r.store.slug === "string")
+        return r.store;
+    if (r.store === undefined && Array.isArray(r.stores) && r.stores.length === 1)
+        return r.stores[0];
+    return null;
+}
+export const listStores = (c) => c.call("list_stores", {});
+/**
+ * The server answers `list_themes` with a bare array today; accept `{ themes }` too so a later
+ * server that wraps it (structuredContent is meant to be an object) does not break old CLIs.
+ */
+export async function listThemes(c, store) {
+    const r = await c.call("list_themes", { store });
+    if (Array.isArray(r))
+        return r;
+    if (r && typeof r === "object" && Array.isArray(r.themes))
+        return r.themes;
+    throw new ServerError("Unexpected list_themes answer from the server.", 200);
+}
+export const createDraft = (c, store, name, fromThemeId) => c.call("create_draft", { store, name, ...(fromThemeId ? { fromThemeId } : {}) });
+export const getThemeFiles = (c, store, themeId) => c.call("get_theme_files", { store, ...(themeId ? { themeId } : {}) });
+export const putThemeFiles = (c, store, themeId, files, force) => c.call("put_theme_files", { store, themeId, files, ...(force ? { force: true } : {}) });
+export const validateThemeFiles = (c, store, themeId, files) => c.call("validate_theme_files", { store, ...(themeId ? { themeId } : {}), files });
+export const getPreviewUrl = (c, store, themeId) => c.call("get_preview_url", { store, themeId });
+export const submitForApproval = (c, store, themeId, title, description) => c.call("submit_for_approval", {
+    store,
+    themeId,
+    title,
+    ...(description ? { description } : {}),
+});
+export const listSectionStarters = (c) => c.call("list_section_starters", {});
+export const deleteThemeFiles = (c, store, themeId, files) => c.call("delete_theme_files", { store, themeId, files });
+export const listThemeFileVersions = (c, store, filePath, limit) => c.call("list_theme_file_versions", { store, path: filePath, ...(limit ? { limit } : {}) });
+export const restoreThemeFileVersion = (c, store, themeId, filePath, version) => c.call("restore_theme_file_version", { store, themeId, path: filePath, version });
+/** A localized name in the reader's language: English for a terminal, else Arabic, else whatever is there. */
+export function nameOf(name) {
+    if (!name)
+        return "";
+    if (typeof name === "string")
+        return name;
+    return name["en"] ?? name["ar"] ?? Object.values(name)[0] ?? "";
+}