# Zalify CLI Plain-text reference for developers and AI agents. Canonical URL: https://zalify.com/cli.txt Package: @zalify/cli (npm) — bin name "zalify". Wrapper package "zalify" lets you run `npx zalify …` or `npm i -g zalify`. Requires Node >= 20. Source of truth for behavior is always `zalify --help` and `zalify --help` of your installed version. The Zalify CLI authors a commerce brand, launches its hosted shop, runs its ad accounts as files, and keeps the shop's theme up to date — the full lifecycle of a Zalify brand, from empty folder to live domain and running ads, without holding any infrastructure or ad-platform credentials on your machine. ## INSTALL npm i -g zalify # or: pnpm add -g zalify / npx zalify … zalify self-update # later updates (auto-detects pnpm/bun/npm) ## THE COMMAND MODEL — FOUR NOUNS, FOUR OBJECTS brand = the DATA a brand folder on disk: product catalog, brand voice guide, image manifest. Authoring happens here, before any account exists. shop = the SHOP the Zalify-hosted deployment at .myzalify.com: GitHub repo + hosting + domain, provisioned server-side. ads = the AD OPS a brand instance: a git repo holding the ad accounts as files (campaigns, ad sets, ads, media plans, policy), plus the daily report. theme = the CODE the storefront source code, distributed like a Shopify theme: a versioned copy you own, with tool-assisted upgrades that keep your edits. Rules of thumb: - Anything that reads or writes a brand folder is `zalify brand …` and the folder argument defaults to the current directory. - Anything about the live deployment is `zalify shop …`; inside a scaffolded shop repo (or a brand folder), shop commands need no argument — the directory identifies the shop. - Anything about source code and versions is `zalify theme …`. - Anything about ad accounts is `zalify ads …`; inside a brand- instance checkout the folder decides which workspace it acts on. ## THE GOLDEN PATH (empty folder → live shop) 1. zalify brand init brands/my-brand # author the data (no login) # fill in brand.md, catalog.json, images/manifest.json zalify brand validate brands/my-brand 2. zalify login zalify workspace set 3. zalify shop create my-brand # live at my-brand.myzalify.com # in ~4 min # already scaffolded with `theme create`? → zalify shop link my-brand 4. cd brands/my-brand && zalify brand push --prune 5. zalify brand images generate && zalify brand images attach 6. zalify shop open # see it live Later (inside the shop folder): zalify theme status # what have I edited? zalify theme upgrade # new theme version, edits kept The shop folder and the brand folder are separate directories; give both the brand's slug as their basename so brand pushes refresh the right shop. Ads, once the workspace's Meta account is connected: zalify ads create ads/my-brand && cd ads/my-brand zalify ads pull # the live account as files zalify ads new spring-sale # or edit a pulled campaign zalify ads diff # what would change zalify ads apply # execute; creations land PAUSED zalify ads report # yesterday vs the day before ## AUTHENTICATION zalify login Opens the browser (app.zalify.com), mints a user-scoped API key stored in ~/.zalify/config.json (0600). One login covers every workspace you belong to. Keys expire after 90 days. zalify logout Deletes the stored credentials. zalify whoami Verifies the key; shows user, workspace, plan, key age. zalify workspace Lists your workspaces (* = active). zalify workspace set Switches the active workspace — the Shopify store commands target. Local only, no re-login. This is the ONLY sticky state the CLI keeps; shops resolve from context, not from a mode. Inside a brand-instance checkout the folder decides: `ads` commands read the checkout's own workspace (.zalify/brand-repo.json, or identity.yaml for folders downloaded from AdsBuddy) and act as that workspace — no `workspace set` first, and no risk of pulling one brand's campaigns into another's folder. `workspace set` still matters outside any checkout, and for `ads create`, which provisions a NEW brand into the workspace you chose. Credential model: the CLI holds only your Zalify user key. Shopify Admin access, ad-platform tokens, GitHub, and hosting credentials live server-side at Zalify — Shopify calls go through Zalify's authenticated Admin proxy, repo pushes use short-lived (1 hour) repo-scoped tokens minted per push, and the shop's cache-refresh secret never leaves the server. ## zalify brand — THE DATA zalify brand init [dir] [--name ] [--vertical ] [--currency USD] Scaffolds a brand folder. No login needed. Creates: brand.md brand voice guide (template) catalog.json products + collections (worked example, plus the mandatory best-sellers and sale collections) images/manifest.json one entry per shot + shared style/ modelStyle/bannerStyle art-direction prefixes. Product shots carry a handle; "type": "banner" entries (hero slides, editorial banners — hero-1.png + hero-1-mobile.png naming) have no handle and set "size" ("1536x1024" landscape / "1024x1536" portrait; default "1024x1024"). Theme templates reference banners by their images/assets.json URL. store.json the Shopify store this brand connects to AUTHORING.md THE RULES — complete authoring contract (catalog schema, collection-tag mechanics, naming and pricing conventions, image prompt-safety). An agent can produce a complete brand from AUTHORING.md alone. zalify brand validate [dir] Lints the folder against the rules: unique kebab-case handles, 2-decimal string prices, variant/option arity, every collection tag resolves to a collection rule, sale products carry real compare-at prices, manifest entries map to real products, alt text present. Exit code 1 on problems. zalify brand push [dir] [--prune] [--shop ] Pushes catalog.json to the active workspace's Shopify store via Zalify's Admin proxy: products (idempotent by handle), smart collections (tag rules), Online Store publication. --prune deletes store products (matching the catalog vendor) that are absent from catalog.json. Afterwards auto-refreshes every ready shop matching the brand's slug (--shop limits it to one). zalify brand images generate [dir] Generates the manifest's missing images on Zalify's infrastructure as a durable background job; the CLI polls and downloads results. Resumable: re-run to retry only failures — produced files are checksummed against the asset library, never re-billed. Finished masters land in the Zalify asset library and locally under images/; images/assets.json is the committed index (the PNG masters themselves stay out of git). zalify brand images attach [dir] [--shop ] Attaches generated images to their Shopify products per the manifest. Idempotent — already-attached files are skipped and "banner" entries (no product) are ignored. Auto-refreshes matching shops afterwards. zalify brand images push [dir] zalify brand images pull [dir] Sync image masters with the Zalify asset library (sha256 dedup). push uploads local masters; pull restores them on a fresh clone. ## zalify shop — THE HOSTED SHOP zalify shop create [-t nextjs] [--editor] [--to ] [--no-install] [--no-git] One-command launch. Zalify's server provisions everything (no infra credentials on your machine): mints a Shopify Storefront API token via the workspace's store connection, creates a private GitHub repo, a hosting project linked to it (with env vars and a server-held cache-refresh secret), and the domain .myzalify.com. The CLI then scaffolds the theme locally, writes .zalify/site.json (linking the folder to its site), pushes with a short-lived repo token, and waits for the first deployment to serve. The slug is the directory basename. Also writes theme/pixel.json (the workspace id) — the theme embeds the Zalify Pixel (cdn.zalify.com/llms.txt) when it exists: auto pageviews, add_to_cart / begin_checkout events, ad-platform forwarding. Delete the file to disable; self-host scaffolds add it by hand. Name the directory after the brand's slug so auto-refresh links brand pushes to this site. Requires: active workspace with a connected Shopify store (409 NO_CONNECTION otherwise), paid plan (402), unique slug (409 SLUG_TAKEN). must be empty or absent — an existing scaffold attaches with `shop link` instead. zalify shop link [--slug ] [--no-git] Attaches an existing scaffold (from `theme create`) to an already-provisioned shop: fills store credentials into .env, writes .zalify/site.json and theme/pixel.json, pushes, and waits for the deploy. Also the recovery path when `shop create` fails after provisioning. zalify shop [list] Lists the workspace's sites: status, URL, repo. zalify shop refresh [slug-or-dir] Refreshes the live shop's data cache (products, collections, menus, content) so Shopify-side changes appear immediately. The refresh secret stays server-side. Argument optional: inside a shop repo or brand folder the shop is inferred; with exactly one shop in the workspace it is assumed; otherwise name it. zalify shop domain-sync [slug-or-dir] Re-points the shop at the platform's current root domain (the previous domain 308-redirects). Only relevant after a platform suffix change. zalify shop open [slug-or-dir] Opens the live shop in your browser. Same resolution rules. Deploys happen on git push (the repo is linked to hosting). A redeploy does NOT clear the data cache — that is what refresh is for, and brand push / brand images attach do it automatically. ## zalify ads — THE AD OPS A brand instance is a private GitHub repo that holds a brand's ad accounts as files. You edit files; `diff` shows what would change on the platform; `apply` executes it. Ad-platform tokens stay server-side, and every read comes from what Zalify has already ingested, so pulling and diffing never touch the ad platform. Drafting and decisions also happen in Zalify AdsBuddy; both land in the same repo. The workspace must be onboarded to Zalify ads (Meta connected) first. Set up: zalify ads create Provisions the brand-instance repo, scaffolds the starter (identity.yaml, brand.yaml, policy/config.yaml, campaigns/, media-plans/, signals/, decisions/), and pushes with a short-lived repo token. Writes .zalify/brand-repo.json so later commands run with no arguments. The directory's basename becomes the instance slug — use the workspace's store slug. zalify ads [list] The workspace's brand instances and their status. zalify ads remove Deprecates a brand instance. The GitHub repo itself is left untouched — deleting campaign intent is a decision for a human. The operate loop (run from inside the checkout): zalify ads pull [--account ] [--days ] [--force] The existing ad accounts as files: each campaign with ads seen in the last days (default 30) lands as accounts///campaign.yaml, with accounts/.bindings.json mapping each file node to its platform id. Local edits are protected: an unedited file fast-forwards, an edited one is kept and named (--force overwrites). Nothing is ever deleted automatically — a campaign gone upstream leaves its file behind with a warning. zalify ads new [--account ] [--objective ] [--budget "$60/day"|"$900 total"] [--country US,CA] [--link ] Scaffolds a campaign FOLDER: campaign.yaml (objective, budget, audience, default copy) plus creatives/. Every image dropped into creatives/ becomes an ad named after its file; a sidecar .copy.yaml gives one ad its own copy; a subfolder of creatives/ targets the ad set with that name. Duplicate a campaign with cp -r. zalify ads creative generate --prompt [--orientation square|landscape|portrait] [--ref ] [--name ] Generates one ad image (placement safe zones, product fidelity against the --ref photos) straight into the campaign's creatives/. Delete the file to reject it. zalify ads diff Your files vs the ingested account: what apply would do. Creatives upload first (checksum-deduplicated, stored once). Read-only. Invalid files are listed with the field at fault; exit code 1 when any file is invalid. zalify ads apply [-y] [--activate] Shows the diff, asks, then executes it as a server-side job the CLI follows to the end: - everything created lands PAUSED — always - budget edits apply to existing campaigns and ad sets - active → paused always executes - paused → active (turning spend on) is refused unless you pass --activate Each change prints a receipt (✓/✗, platform id, error or warning); new platform ids are recorded in accounts/.bindings.json — commit it. A failed step is reported, never blindly retried: re-run `ads diff` to see what landed before applying again. -y skips the prompt (required when not in a terminal). Reading results: zalify ads report [--date YYYY-MM-DD] [--platform all|meta|google] [--account ] The daily report in the terminal: one day (default: yesterday) against the day before it. Metrics follow the brand's objective, set in Zalify: sales purchases, cost per purchase, platform ROAS, and first-party revenue leads leads, cost per lead traffic impressions, clicks, CTR, CPC, CPM Metrics that do not apply to the objective are omitted, never printed as 0. "Where the money moved" lists the campaigns whose spend changed most, each with its cost per outcome and how that moved. "Account changes" counts that day's edits by people vs platform automation, broken down by category (budget, status, targeting, bidding, schedule, name, created, removed). A day still running is marked with the hours elapsed. zalify ads status Access and credential expiry per platform, ingestion freshness (with per-account failures), first-party revenue join coverage, recorded plans and pending proposals. Exit code 1 when the service reports problems. zalify ads digest [dir] Prints the checkout's signals/latest.json — the numbers Zalify commits to the repo daily and agents draft against. Local only. zalify ads plan [list] zalify ads plan show Media plans recorded for this brand. zalify ads open Opens the daily report in app.zalify.com. zalify ads doctor [dir] Checks that have each broken once: checkout ↔ record link, workspace match, slug alignment, consent drift, brand timezone vs ad-account timezone (a mismatch corrupts every per-day figure), credential expiry and degraded accounts. Exit code 1 on any failure. ## zalify theme — THE CODE The theme is distributed the way Shopify themes are: you own a copy of the source, and upgrades are tool-assisted rather than forced. Every scaffold carries .zalify/theme.json — a checksum manifest of each theme-owned file as shipped. Your customizations belong in: theme/ settings_data.json, templates/*.json, locales/*.json — the merchant-owned surface, NEVER touched by upgrades .env store credentials, never touched anything you add (public/ assets, new files) — untouched zalify theme create [-t liquid|hydrogen|nextjs] [--editor] [--store-domain ] [--storefront-token ] [--to ] [--no-install] [--no-git] Scaffold ONLY — the self-host path (deploy anywhere you like). `shop create` is the fully-hosted launch and uses this internally; a self-hosted scaffold moves to hosting later with `shop link`. Without store credentials the scaffold runs against mock.shop demo data. Installs the storefront-kit agent skills (.agents/skills, .claude/skills) for the kit version it ships. No login needed. zalify theme status [dir] Which theme-owned files have you edited? Checksums the working tree against the manifest: clean / edited / missing. zalify theme upgrade [dir] [--to ] [--dry-run] [--install] Moves the copy to a newer theme release: - files you never touched are overwritten with the new version - files you edited are 3-way-merged (base = your current version's original); conflicts leave standard markers - files added/deleted upstream are applied when safe - theme/, .env, and your own files are never touched - package.json is merged per-key (your added deps kept) --dry-run reports the classification without writing. The manifest is rewritten to the new version and the storefront-kit agent skills are re-synced; `theme status` shows drift again afterwards. ## MAINTENANCE zalify self-update Update the CLI in place. zalify version Version + update check. zalify --help Full surface; every group has --help too. ## FILE CONTRACTS (quick reference) Brand folder (created by `brand init`, consumed by brand push/images): brand.md, catalog.json, catalog/ (generated), images/manifest.json, images/assets.json (committed index), images/*.png (not committed), store.json, AUTHORING.md Shop scaffold (created by `shop create` / `theme create`): .zalify/theme.json upgrade contract (checksums; do not edit) .zalify/site.json link to the hosted shop (shop create / link) theme/pixel.json the workspace id the Zalify Pixel reports to theme/ YOUR settings/templates/locales overrides .env store credentials (NEXT_PUBLIC_STORE_DOMAIN, NEXT_PUBLIC_STOREFRONT_API_TOKEN) Brand-instance checkout (created by `ads create`): .zalify/brand-repo.json link to the instance + workspace stamp identity.yaml workspace, brand slug, consent, ad account ids brand.yaml brand voice and guardrails for drafting policy/config.yaml per-brand thresholds (versioned in git) accounts///campaign.yaml one campaign each accounts///creatives/ files that become ads accounts/.bindings.json file node → platform id ledger (commit it) media-plans/, decisions/, signals/ written by Zalify; read, don't edit catalog.json essentials (full rules in the scaffolded AUTHORING.md): products[]: handle (unique kebab-case), title, descriptionHtml, type, tags, options (0-3), variants[] (options match arity, price "29.00" strings, optional compareAtPrice), optional seo collections[]: smart collections — a product joins collection X by carrying tag "collection:X"; the collection rule is { "tag": "collection:X" }. best-sellers and sale are mandatory; sale products need a real compareAtPrice and the collection:sale tag. pages[]: the standard store pages ({handle, title, bodyHtml}) — about, shipping-delivery, returns-exchanges, faq, privacy-policy, terms-of-service. Upserted by brand push, linked from the footer menu. /pages/contact ships with every store — link it, don't author it. discounts[]: code discounts ({code, percentOff, title?}) created by brand push — keep the scaffold's WELCOME20: it's the code the theme's cart voucher banner shows, so Apply actually works. menus: {"main-menu": [...], "footer": [...]} — items are { title, url, items? }, relative URLs, max 3 levels; URLs must reference handles that exist in this file. brand push upserts them (full item tree replaced — the catalog is the source of truth). Nested main-menu items open the theme's mega panel; nested footer items become footer columns (Shop / Help / Company is the standard trio). ## ERRORS AND TROUBLESHOOTING 401 Unauthorized (suddenly, mid-batch) Bursty commands can trip the per-key rate limit; it clears in about a minute. All push/attach commands are idempotent — re-run. 402 UPGRADE_REQUIRED The feature (asset library, shop hosting) needs a paid plan. 409 NO_CONNECTION The workspace has no connected Shopify store — connect it in the Zalify dashboard first. 409 SLUG_TAKEN Shop slugs are global; pick another directory name. 404 NOT_ONBOARDED (ads commands) The workspace is not set up for Zalify ads yet — connect Meta in the Zalify dashboard, or contact Zalify. Refused activation (ads apply) Turning spend on needs `--activate`; everything else in the run still applied. 428 SCOPES_MISSING A new Shopify install grants only core permissions; brand push and image attach need the developer set. The error includes a reconnect URL that asks for exactly those — approve once. Shop setup failed Retry setup, or delete and start over, from the Websites page in the Zalify dashboard (the error prints the link). A deleted shop's slug stays reserved. 409 on shop domain-sync The shop runs on the merchant's own domain; domain-sync only moves Zalify-assigned addresses and leaves custom domains alone. Image generation rejected (safety_violations) Reword the prompt in images/manifest.json and re-run `brand images generate` — see AUTHORING.md's prompt-safety rules (applies to human-model shots; layered/covered styling, no "young …" phrasing, chin crops). Stale data on the live site `zalify shop refresh` — deploys alone never clear the data cache. The previous spellings `zalify z1shop …` and `zalify site …` still work and print their new home (`zalify shop …`). Older spellings (store, shopify, images, assets, storefront) have been removed. — Generated for zalify.com. Questions: ryan@zalify.com