AUTHENTICATION

1 · Ensure an authenticated CLI session

Secret boundary — mandatory

Never read authentication material or tokens into agent context. Never emit them to stdout, stderr, logs, prompts, or tool results.

If it’s non-zero, log in yourself — don’t punt to the user and stop. A foreground command that exits in seconds, one JSON event per line:

If you’d rather not execute it

Read ../../entry/bootstrap.mjs and do the same thing yourself. What matters:

Send the user that URL + code, then stop — nothing moves until they act. The detached login lands the session on its own; resume with whoami (exit 0). Codes last ~10 min; after that, start a new login and surface the new code.

2 · Mint the token

• Mints a site-scoped REST token. Mint once per run and never re-mint — the CLI returns a byte-identical token on every call within a run (it caches internally), so re-minting only costs ~1.25 s of startup. Cache $TOKEN and $SITE_ID in scratch.
• Use npx @wix/cli@latest token … (not bare wix token) so npx resolves the project-local CLI.
• The first --site "$SITE_ID" call is the source of truth for SITE_ID; bind it in scratch, don’t re-derive mid-run.

3 · clientId for the frontend

The frontend’s public clientId is the appId field in wix.config.json — for a managed headless project the OAuth app id and the client id are the same value (app-id === client-id). It’s the same file you already read for siteId (§2), so read appId straight from there — do not query the OAuth-apps API, search the docs, or mint anything to obtain it. (It’s the public OAuth id, not a secret.)

REST call shape

• Authorization: Bearer $TOKEN — the Bearer prefix is required.
• wix-site-id: $SITE_ID — required by every site-scoped family; include it always.
• Content-Type: application/json — on every POST/PATCH body.
• Parsing the response: -w appends a HTTP_STATUS:<code> line after the JSON body. grep that line for the status, but parse the body separately — piping the combined output to a JSON parser (python3 -m json.tool, json.load, jq) chokes on the trailing status line (Extra data: line 2 …). Capture the body to a file with -o body.json (status still comes from -w), or drop the last line, before parsing.

Recovery ladder

Re-mint is not a recovery step (the token is byte-identical) — retry the same call with the cached token.