@facet-llc/schema-generator

Facet schema-generator CLI — crawls a Shopify Admin REST API and upserts a facet.yaml manifest into the site you own on Facet.

npx @facet-llc/schema-generator shopify \
  --shop-domain=acme.myshopify.com \
  --admin-token=shpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

What it does

1. Asks Facet for a device code, opens your browser to https://app.facet.llc/onboarding/cli?code=XXXX-XXXX.
2. You sign in (Google or Microsoft Entra ID) and click Approve.
3. The CLI gets a 30-day token tied to your account.
4. Sends { shop_domain, admin_token } to app.facet.llc/api/catalog/generate-from-shopify with the token as Authorization: Bearer ….
5. The server resolves the token → your user → your owned site, then crawls https://<shop>.myshopify.com/admin/api/2024-10/products.json, builds a normalized catalog, emits a facet.yaml manifest, and upserts it into site_manifests.
6. CLI prints a count of imported products + a sample of titles.

Why server-side?

The Supabase service-role key lives only on the Facet server — it never hits your machine. Your Shopify admin token is forwarded in-flight to the server crawler for one run and discarded. Nothing is logged.

Flags

| flag | required | meaning | | -------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | --shop-domain=<handle>.myshopify.com | yes | Validated client-side AND server-side against ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.myshopify\.com$/i. Path/port injection or non-Shopify hosts are rejected before the admin token leaves the CLI. | | --admin-token=shpat_... | yes | Shopify Admin API access token — read_products scope is sufficient. | | --kya-issuer=<url> | no, repeatable | Override the manifest's kya_issuers list. Defaults to whatever the server picks for your site. |

Environment

| var | meaning | | ---------------- | ------------------------------------------------------------------------ | | FACET_API_HOST | Override the default https://app.facet.llc target. Useful for staging. | | FACET_DEBUG=1 | Log full error stack traces. |

Authoring a Shopify admin token

1. In Shopify admin, go to Settings → Apps and sales channels → Develop apps.
2. Create a new private app, grant read_products (and optionally read_inventory).
3. Copy the Admin API access token (shpat_...).
4. Pass it via --admin-token to this CLI.

The token is consumed once per run by the Facet server; it is not stored. You can rotate or revoke it at any time from the Shopify admin without affecting your Facet account.