@cerkel/cli 0.0.0-stage → 1.0.1

package/dist/commands/args.js

@@ -0,0 +1,107 @@
+import { str } from "../command.js";
+import { CliError } from "../errors.js";
+// ---------------------------------------------------------------------------
+// Turning flags into the JSON arguments the MCP tools take. The CLI does no business logic: it
+// only reshapes what was typed (text per language, "SKU:qty" pairs, key=value fields) and sends
+// it; the server validates every value and its refusal is printed verbatim.
+// ---------------------------------------------------------------------------
+/** Repeatable string flag values (`--title a --title b`). */
+export const list = (v, k) => {
+    const x = v[k];
+    if (Array.isArray(x))
+        return x.filter((s) => typeof s === "string");
+    return typeof x === "string" ? [x] : [];
+};
+const LANG_PREFIX = /^([a-z]{2,3}):([\s\S]*)$/;
+/**
+ * Text per language from a repeatable flag: `--title "en:Loofah" --title "ar:ليفة"`, or plain
+ * `--title "ليفة"` for the `--lang` language (default ar, the stores' default). `""` after the
+ * prefix removes that language. Undefined when the flag was not given.
+ */
+export function localized(v, k) {
+    const items = list(v, k);
+    if (!items.length)
+        return undefined;
+    const lang = str(v, "lang") ?? "ar";
+    const out = {};
+    for (const item of items) {
+        const m = LANG_PREFIX.exec(item);
+        if (m)
+            out[m[1]] = m[2];
+        else
+            out[lang] = item;
+    }
+    return out;
+}
+/** `JL-90:5` pairs (`--line`) → [{ variant, quantity }]. */
+export function lines(v, k) {
+    const items = list(v, k);
+    if (!items.length)
+        return undefined;
+    return items.map((item) => {
+        const i = item.lastIndexOf(":");
+        const variant = i > 0 ? item.slice(0, i).trim() : item.trim();
+        const qty = i > 0 ? Number(item.slice(i + 1)) : 1;
+        if (!variant || !Number.isInteger(qty) || qty < 1)
+            throw new CliError(`--${k} "${item}": write it as <sku>:<quantity>, e.g. JL-90:3.`);
+        return { variant, quantity: qty };
+    });
+}
+/** A value typed on the command line: JSON when it parses as JSON (numbers, true/false, null, [..]), else the text. */
+const loose = (s) => {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return s;
+    }
+};
+/** `key=value` pairs (`--field material=cotton`) → a record; values read loosely as JSON. */
+export function pairs(v, k, opts = {}) {
+    const items = list(v, k);
+    if (!items.length)
+        return undefined;
+    const out = {};
+    for (const item of items) {
+        const i = item.indexOf("=");
+        if (i < 1)
+            throw new CliError(`--${k} "${item}": write it as key=value.`);
+        out[item.slice(0, i).trim()] = opts.loose === false ? item.slice(i + 1) : loose(item.slice(i + 1));
+    }
+    return out;
+}
+/** A comma-separated flag (`--tags a,b`) → a list; "" → []. */
+export const csvList = (s) => s === undefined ? undefined : s.split(",").map((x) => x.trim()).filter(Boolean);
+/** A whole number, or a usage error naming the flag. */
+export function int(s, name) {
+    if (s === undefined)
+        return undefined;
+    const n = Number(s.trim());
+    if (!Number.isInteger(n))
+        throw new CliError(`${name} must be a whole number (got "${s}").`);
+    return n;
+}
+/** `on`/`off`, `yes`/`no`, `true`/`false`. */
+export function onOff(s, name) {
+    if (s === undefined)
+        return undefined;
+    const t = s.trim().toLowerCase();
+    if (["on", "yes", "true", "1"].includes(t))
+        return true;
+    if (["off", "no", "false", "0"].includes(t))
+        return false;
+    throw new CliError(`${name} takes on or off (got "${s}").`);
+}
+/** Only the keys whose value is defined. */
+export const defined = (o) => Object.fromEntries(Object.entries(o).filter(([, x]) => x !== undefined));
+/** "none"/"null"/"-" → null (clear it), else the text. */
+export const nullable = (s) => s === undefined ? undefined : ["none", "null", "-"].includes(s.trim().toLowerCase()) ? null : s;
+/** A per-language value as one string: English, else Arabic, else any. */
+export const textOf = (l) => {
+    if (!l || typeof l !== "object")
+        return typeof l === "string" ? l : "";
+    const r = l;
+    return r["en"] || r["ar"] || Object.values(r).find(Boolean) || "";
+};
+export const LANG_OPTION = { lang: { type: "string" } };
+export const TEXT_HELP = 'Text flags take "en:Text" / "ar:نص" (repeat for each language), or plain text in --lang (default ar). "en:" alone removes English.';

package/dist/commands/auth.js

@@ -0,0 +1,255 @@
+import { createHash, randomBytes } from "node:crypto";
+import { apiOrigin } from "../api-url.js";
+import { listStores, oneStoreOf } from "../api.js";
+import { AuthError, CliError, isNotOneStore } from "../errors.js";
+import { table } from "../format.js";
+import { envToken } from "../env.js";
+import { bookStores, isStoreSlug } from "../logins.js";
+/** What to say when a token is not tied to exactly one store — without naming any of them. */
+const noStoreLine = (who) => who.stores.length > 1
+    ? "this token reaches more than one store, which cerkel no longer uses. Create a token for one store in Settings → MCP."
+    : "none — this login cannot reach its store right now.";
+function describe(s, who, origin) {
+    const you = who.you;
+    const name = [you?.name, you?.email ? `<${you.email}>` : null].filter(Boolean).join(" ");
+    s.out(`Logged in to ${origin}${name ? ` as ${name}` : ""}`);
+    const own = oneStoreOf(who);
+    // One store per login: this is the whole of what it can reach. Never a list of other stores.
+    s.out(`Store: ${own ? `${own.name} (${own.slug})` : noStoreLine(who)}`);
+    if (who.token?.prefix || who.token?.name) {
+        s.out(`Token: ${who.token.prefix ?? ""}…${who.token.name ? ` (${who.token.name})` : ""}`);
+    }
+    s.out(`Permissions: ${who.grantedPermissions.length ? who.grantedPermissions.join(", ") : "(none)"}`);
+}
+/** How long the browser half may take: signing in with a WhatsApp code and an authenticator included. */
+export const BROWSER_LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+const b64url = (b) => b.toString("base64url");
+const checkSlug = (store) => {
+    if (store === undefined)
+        return null;
+    const slug = store.trim().toLowerCase();
+    if (!isStoreSlug(slug))
+        throw new CliError(`"${store}" is not a store slug: use the store's short name, lowercase letters, digits and hyphens (e.g. justloofah-jo).`);
+    return slug;
+};
+/**
+ * Shopify-CLI-style login: open the admin in the browser, the person signs in as they always do,
+ * picks the store (pre-selected by --store) and presses Allow, and the admin hands a token for THAT
+ * store back to a listener on 127.0.0.1. PKCE means the one-time code in that redirect is useless to
+ * anyone but this process (see the admin's lib/cli-login.ts for the server half).
+ */
+async function browserLogin(s, origin, store) {
+    const verifier = b64url(randomBytes(32));
+    const challenge = b64url(createHash("sha256").update(verifier).digest());
+    const state = b64url(randomBytes(24));
+    const lb = await s.ctx.listenLoopback();
+    let q;
+    try {
+        const url = new URL("/cli/authorize", origin);
+        const query = new URLSearchParams({ port: String(lb.port), state, challenge, device: s.ctx.hostname.slice(0, 60) });
+        if (store)
+            query.set("store", store);
+        url.search = query.toString();
+        s.err(`Opening your browser to sign in to Cerkel${store ? ` for ${store}` : ""}. Choose the store, press Allow there, then come back here.`);
+        s.err(`If it does not open, visit: ${url.href}`);
+        await s.ctx.openUrl(url.href);
+        try {
+            q = await lb.waitForCallback(BROWSER_LOGIN_TIMEOUT_MS);
+        }
+        catch {
+            throw new CliError("Timed out waiting for the browser (5 minutes). Run `cerkel login` again.");
+        }
+    }
+    finally {
+        lb.close();
+    }
+    if (q.get("state") !== state)
+        throw new CliError("The browser answered a different login request. Run `cerkel login` again.");
+    if (q.get("error"))
+        throw new CliError(q.get("error") === "access_denied" ? "Sign-in was cancelled in the browser." : `Sign-in failed in the browser (${q.get("error")}).`);
+    const code = q.get("code");
+    if (!code)
+        throw new CliError("The browser returned no sign-in code. Run `cerkel login` again.");
+    let res;
+    try {
+        res = await s.ctx.fetch(new URL("/api/cli/token", origin).href, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({ code, verifier }),
+            redirect: "error",
+        });
+    }
+    catch (e) {
+        throw new CliError(`Could not reach ${origin}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || typeof body.token !== "string") {
+        throw new CliError(typeof body.message === "string" ? body.message : `Sign-in failed (HTTP ${res.status}). Run \`cerkel login\` again.`);
+    }
+    return body.token;
+}
+export async function login(s, opts = {}) {
+    const co = await s.checkout();
+    const url = s.api(co?.state);
+    const origin = apiOrigin(url);
+    // Inside a theme folder, `cerkel login` means the folder's own store.
+    const wanted = checkSlug(opts.store) ?? co?.state.store ?? null;
+    const env = envToken(s.ctx.env);
+    let token;
+    if (env) {
+        // CI: verify what the pipeline will use, but never copy an injected secret into a keychain.
+        s.err(`${env.name} is set; verifying it. It is used instead of any stored login, so nothing is saved.`);
+        token = env.value;
+    }
+    else if (!s.ctx.io.isTTY) {
+        token = (await s.ctx.io.readStdin()).trim();
+    }
+    else if (opts.token) {
+        s.err(`Create a token for one store in the Cerkel admin at Settings → AI assistant connection (MCP) (${origin}).`);
+        token = (await s.ctx.io.promptSecret("Paste your token (input hidden): ")).trim();
+    }
+    else {
+        token = await browserLogin(s, origin, wanted);
+    }
+    if (!token)
+        throw new CliError("No token entered.");
+    s.addSecret(token);
+    let who;
+    try {
+        who = await listStores(s.clientWith(url, token));
+    }
+    catch (e) {
+        if (e instanceof AuthError && isNotOneStore(e.reason)) {
+            throw new AuthError("Token not saved: it is not tied to one store. Create a token for one store in Settings → MCP, or run `cerkel login --store <slug>`.", e.reason);
+        }
+        if (e instanceof AuthError)
+            throw new AuthError(`Token not saved: ${e.message}`, e.reason);
+        throw e;
+    }
+    const own = oneStoreOf(who);
+    if (!own) {
+        throw new AuthError(who.stores.length > 0
+            ? "Token not saved: it reaches more than one store, which cerkel no longer uses. Create a token for one store in Settings → MCP, or run `cerkel login --store <slug>`."
+            : "Token not saved: it cannot reach its store right now. Ask an admin to check your access in Settings → Staff.");
+    }
+    if (wanted && own.slug !== wanted)
+        s.err(`Note: this login is for ${own.slug}, not ${wanted}.`);
+    if (!env) {
+        // Keep every other store's login: a Raizn-team member works on several stores.
+        await s.tidyLegacy(url);
+        const book = await s.book(url);
+        const where = await s.saveBook(url, { logins: { ...book.logins, [own.slug]: token }, legacy: book.legacy });
+        s.err(where === "keychain" ? `Login for ${own.slug} saved to the system keychain.` : `Login for ${own.slug} saved to the credentials file (no system keychain available).`);
+    }
+    describe(s, who, origin);
+    return 0;
+}
+export async function logout(s, opts = {}) {
+    const co = await s.checkout();
+    const url = s.api(co?.state);
+    const origin = apiOrigin(url);
+    // A 0.1.x login is filed under its store first (or dropped), so "which login" means the same as everywhere.
+    if (!opts.all)
+        await s.tidyLegacy(url);
+    const book = await s.book(url);
+    const stores = bookStores(book);
+    if (opts.all) {
+        if (stores.length === 0 && !book.legacy)
+            s.out(`No stored login for ${origin}.`);
+        else {
+            await s.saveBook(url, { logins: {}, legacy: null });
+            s.out(`Logged out of every store on ${origin}.`);
+        }
+    }
+    else {
+        // Inside a theme folder, the folder's store; with one login, that one; otherwise say which.
+        const store = checkSlug(opts.store) ?? co?.state.store ?? (stores.length === 1 && !book.legacy ? stores[0] : null);
+        if (store) {
+            if (book.logins[store]) {
+                const rest = { ...book.logins };
+                delete rest[store];
+                await s.saveBook(url, { logins: rest, legacy: book.legacy });
+                s.out(`Logged out of ${store} on ${origin}.`);
+            }
+            else
+                s.out(`No stored login for ${store} on ${origin}.`);
+        }
+        else if (stores.length === 0 && book.legacy) {
+            await s.saveBook(url, { logins: {}, legacy: null });
+            s.out(`Logged out of ${origin}.`);
+        }
+        else if (stores.length === 0) {
+            s.out(`No stored login for ${origin}.`);
+        }
+        else {
+            throw new CliError("You are logged in to more than one store. Pass --store <slug>, or --all to log out of every store.");
+        }
+    }
+    const still = envToken(s.ctx.env);
+    if (still)
+        s.err(`Note: ${still.name} is still set in this environment, and commands will keep using it.`);
+    return 0;
+}
+export async function whoami(s, opts = {}) {
+    if (opts.all)
+        return logins(s);
+    const co = await s.checkout();
+    const store = checkSlug(opts.store);
+    const c = await s.client(co?.state, store);
+    describe(s, await listStores(c), apiOrigin(c.url));
+    return 0;
+}
+export async function stores(s, opts = {}) {
+    const co = await s.checkout();
+    const store = checkSlug(opts.store);
+    const r = await listStores(await s.client(co?.state, store));
+    const own = oneStoreOf(r);
+    if (!own) {
+        s.err(`Store: ${noStoreLine(r)}`);
+        return 0;
+    }
+    for (const line of table([["SLUG", "NAME"], [own.slug, own.name]]))
+        s.out(line);
+    return 0;
+}
+/**
+ * Your OWN logins on this computer, one per store. It is the one command that lists stores you are
+ * logged in to — that data is on your own disk — and each line is checked with the server using
+ * that login's own token, so nothing is learned about any store but the login's own.
+ */
+export async function logins(s) {
+    const co = await s.checkout();
+    const url = s.api(co?.state);
+    const origin = apiOrigin(url);
+    const envSet = envToken(s.ctx.env);
+    if (envSet)
+        s.err(`Note: ${envSet.name} is set, so commands use it instead of these logins.`);
+    await s.tidyLegacy(url);
+    const book = await s.book(url);
+    const slugs = bookStores(book);
+    if (slugs.length === 0) {
+        s.out(`No logins for ${origin}. Run \`cerkel login --store <slug>\`.`);
+        return 0;
+    }
+    const rows = [["STORE", "NAME", "SIGNED IN AS", "STATUS"]];
+    for (const slug of slugs) {
+        const mark = co?.state.store === slug ? `${slug} *` : slug;
+        try {
+            const r = await listStores(s.clientWith(url, book.logins[slug]));
+            const own = oneStoreOf(r);
+            const status = own?.slug === slug ? "ok" : own ? `for ${own.slug} — run cerkel login --store ${slug}` : "cannot reach its store";
+            rows.push([mark, own?.name ?? "—", r.you?.email ?? r.you?.name ?? "—", status]);
+        }
+        catch (e) {
+            const status = e instanceof AuthError
+                ? isNotOneStore(e.reason) ? `not tied to a store — run cerkel login --store ${slug}` : `signed out — run cerkel login --store ${slug}`
+                : "could not check (offline?)";
+            rows.push([mark, "—", "—", status]);
+        }
+    }
+    for (const line of table(rows))
+        s.out(line);
+    if (co && slugs.includes(co.state.store))
+        s.err("* this folder's store");
+    return 0;
+}

package/dist/commands/call.js

@@ -0,0 +1,67 @@
+import { bool, str } from "../command.js";
+import { storeAndClient, flagsOf } from "../commerce.js";
+import { CliError } from "../errors.js";
+import { table } from "../format.js";
+/**
+ * `cerkel call TOOL --args '{…}' [--allow-writes]` — any MCP tool with JSON arguments, like Shopify's
+ * `store execute`. Read-only by default: a tool the SERVER marks as a write (its `readOnlyHint` in
+ * tools/list) is refused before it is called unless --allow-writes. `--list` prints the tools.
+ * `store` defaults to the login's store when the arguments do not name one.
+ */
+export const CALL_COMMANDS = {
+    call: {
+        usage: "cerkel call <tool> [--args '{\"key\": \"value\"}'] [--allow-writes] [--store <slug>]\n       cerkel call --list",
+        summary: "Call any MCP tool with JSON arguments (read-only unless --allow-writes)",
+        help: [
+            "Prints the tool's answer as JSON. Whether a tool writes comes from the server's own tool list, never from this CLI.",
+            "Write tools accept \"dry_run\": true in --args to see the change without making it.",
+        ],
+        options: { args: { type: "string" }, "allow-writes": { type: "boolean" }, list: { type: "boolean" }, store: { type: "string" }, json: { type: "boolean" } },
+        positionals: true,
+        run: async (s, v, pos) => {
+            const flags = flagsOf(v);
+            const { client, store } = await storeAndClient(s, flags);
+            const tools = await client.listTools();
+            if (bool(v, "list")) {
+                if (pos.length)
+                    throw new CliError("Usage: cerkel call --list");
+                if (flags.json)
+                    s.out(JSON.stringify(tools, null, 2));
+                else
+                    for (const line of table([["TOOL", "KIND", "TITLE"], ...tools.map((t) => [t.name, t.annotations?.readOnlyHint ? "read" : t.annotations?.destructiveHint ? "write (destructive)" : "write", t.title ?? ""])]))
+                        s.out(line);
+                return 0;
+            }
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel call <tool> [--args '{…}'] [--allow-writes]  (cerkel call --list shows the tools)");
+            const tool = tools.find((t) => t.name === pos[0]);
+            if (!tool)
+                throw new CliError(`The server has no tool "${pos[0]}". cerkel call --list shows the tools.`);
+            let args = {};
+            const raw = str(v, "args");
+            if (raw !== undefined) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch (e) {
+                    throw new CliError(`--args is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+                }
+                if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+                    throw new CliError("--args must be a JSON object, e.g. '{\"code\": \"EID10\"}'.");
+                args = parsed;
+            }
+            const writes = tool.annotations?.readOnlyHint !== true;
+            if (writes && !bool(v, "allow-writes")) {
+                throw new CliError(`${tool.name} changes the store. Re-run with --allow-writes to call it (add "dry_run": true to --args to only see the change).`);
+            }
+            // The login's store, unless the tool's schema says it takes none (list_stores…).
+            const props = tool.inputSchema?.["properties"];
+            if ((!props || "store" in props) && args["store"] === undefined)
+                args["store"] = store;
+            const result = await client.call(tool.name, args);
+            s.out(JSON.stringify(result, null, 2));
+            return 0;
+        },
+    },
+};

package/dist/commands/collection.js

@@ -0,0 +1,121 @@
+import { bool, str } from "../command.js";
+import { READ_HELP, READ_OPTIONS, WRITE_HELP, WRITE_OPTIONS, flagsOf, runRead, runWrite } from "../commerce.js";
+import { CliError } from "../errors.js";
+import { table } from "../format.js";
+import { LANG_OPTION, TEXT_HELP, defined, int, localized, nullable, textOf } from "./args.js";
+const DETAIL_OPTIONS = {
+    ...LANG_OPTION,
+    title: { type: "string", multiple: true },
+    description: { type: "string", multiple: true },
+    "seo-title": { type: "string", multiple: true },
+    "seo-description": { type: "string", multiple: true },
+    handle: { type: "string" },
+    image: { type: "string" },
+    sort: { type: "string" },
+    template: { type: "string" },
+};
+const details = (v) => defined({
+    title: localized(v, "title"), descriptionHtml: localized(v, "description"), seoTitle: localized(v, "seo-title"), seoDescription: localized(v, "seo-description"),
+    handle: str(v, "handle"), imageUrl: nullable(str(v, "image")), sortOrder: str(v, "sort")?.toUpperCase(), templateSuffix: nullable(str(v, "template")),
+});
+const membersCommand = (tool, verb, summary, help) => ({
+    usage: `cerkel collection ${verb} <collection> <product>… [--yes] [--dry-run] [--json]`,
+    summary,
+    help: [help, WRITE_HELP],
+    options: WRITE_OPTIONS,
+    positionals: true,
+    run: (s, v, pos) => {
+        const [collection, ...products] = pos;
+        if (!collection || !products.length)
+            throw new CliError(`Usage: cerkel collection ${verb} <collection> <product>…`);
+        return runWrite(s, flagsOf(v), tool, { collection, products });
+    },
+});
+export const COLLECTION_COMMANDS = {
+    "collection list": {
+        usage: "cerkel collection list [search] [--published|--hidden] [--page N] [--store <slug>] [--json]",
+        summary: "Search the store's collections",
+        help: [READ_HELP],
+        options: { ...READ_OPTIONS, published: { type: "boolean" }, hidden: { type: "boolean" }, page: { type: "string" } },
+        positionals: true,
+        run: (s, v, pos) => runRead(s, flagsOf(v), "search_collections", defined({
+            q: pos.join(" ").trim() || undefined, published: bool(v, "published") ? true : bool(v, "hidden") ? false : undefined, page: int(str(v, "page"), "--page"),
+        }), (d) => d.collections.length === 0 ? ["No collections match."] : [
+            ...table([["HANDLE", "SHOWN", "PRODUCTS", "SORT", "TITLE"], ...d.collections.map((c) => [c.handle, c.published ? "yes" : "no", String(c.products), c.sortOrder + (c.smart ? " (smart)" : ""), textOf(c.title)])]),
+            `${d.collections.length} of ${d.total}`,
+        ]),
+    },
+    "collection get": {
+        usage: "cerkel collection get <handle|id> [--store <slug>] [--json]",
+        summary: "Show a collection and its products in order",
+        help: [READ_HELP],
+        options: READ_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel collection get <handle>");
+            return runRead(s, flagsOf(v), "get_collection", { collection: pos[0] }, (c) => [
+                ...table([
+                    ["Collection", `${textOf(c.title)} (${c.handle})`],
+                    ["Shown here", c.published ? "yes" : "no"],
+                    ["Sort", c.sortOrder],
+                    ["Template", c.templateSuffix ? `collection.${c.templateSuffix}` : "default"],
+                ]),
+                "",
+                ...(c.products.length ? table([["#", "HANDLE", "STATUS", "TITLE"], ...c.products.map((p, i) => [String(i + 1), p.handle, p.status, p.title])]) : ["No products."]),
+            ]);
+        },
+    },
+    "collection create": {
+        usage: "cerkel collection create --title <text> [--handle <h>] [--description …] [--image <url>] [--sort manual|best_selling|…] [--product <handle>]… [--yes] [--dry-run] [--json]",
+        summary: "Create a collection, shown in this store",
+        help: ["Sort: MANUAL, BEST_SELLING, ALPHA_ASC, ALPHA_DESC, PRICE_ASC, PRICE_DESC, CREATED, CREATED_DESC.", TEXT_HELP, WRITE_HELP],
+        options: { ...WRITE_OPTIONS, ...DETAIL_OPTIONS, product: { type: "string", multiple: true } },
+        run: (s, v) => {
+            const d = details(v);
+            if (!d["title"])
+                throw new CliError("cerkel collection create needs --title.");
+            const products = Array.isArray(v["product"]) ? v["product"] : [];
+            return runWrite(s, flagsOf(v), "create_collection", { ...d, ...(products.length ? { products } : {}) });
+        },
+    },
+    "collection update": {
+        usage: "cerkel collection update <handle|id> [--title …] [--description …] [--seo-title …] [--seo-description …] [--handle <new>] [--image <url|none>] [--sort <order>] [--template <suffix|none>] [--yes] [--dry-run] [--json]",
+        summary: "Change a collection's title, description, SEO, image, sort order or template",
+        help: ["Only what you pass changes.", TEXT_HELP, WRITE_HELP],
+        options: { ...WRITE_OPTIONS, ...DETAIL_OPTIONS },
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel collection update <handle> [flags]");
+            return runWrite(s, flagsOf(v), "update_collection", { collection: pos[0], ...details(v) });
+        },
+    },
+    "collection add": membersCommand("add_to_collection", "add", "Add products to the end of a collection", "Products already in it stay where they are."),
+    "collection remove": membersCommand("remove_from_collection", "remove", "Take products out of a collection", "The products themselves are not changed."),
+    "collection reorder": membersCommand("reorder_collection", "reorder", "Put a collection's products in this order", "The products you list go first, the rest keep their order after them. Shown when the sort is MANUAL."),
+    "collection publish": {
+        usage: "cerkel collection publish <handle|id> [--yes] [--dry-run] [--json]",
+        summary: "Show a collection in this store",
+        help: [WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel collection publish <handle>");
+            return runWrite(s, flagsOf(v), "publish_collection", { collection: pos[0], published: true });
+        },
+    },
+    "collection unpublish": {
+        usage: "cerkel collection unpublish <handle|id> [--yes] [--dry-run] [--json]",
+        summary: "Hide a collection in this store",
+        help: [WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel collection unpublish <handle>");
+            return runWrite(s, flagsOf(v), "publish_collection", { collection: pos[0], published: false });
+        },
+    },
+};