Shoplazza CLI troubleshooting
Common issues with Shoplazza CLI and how to resolve them. For AI-agent-specific issues, see the AI Toolkit troubleshooting.
shoplazza: command not found
The binary isn't on your PATH. If you installed via npm, ensure your global npm bin directory is on PATH. If you used the shell script or a binary, it installs to /usr/local/bin (or ~/.local/bin for make install) — add that directory to PATH. Verify:
shoplazza --version
Authentication fails or a token expired
Check your current state:
shoplazza auth status
Re-authenticate if the token is missing or expired:
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders
"Insufficient scope" errors
When your token lacks a scope, the API rejects the call (HTTP 403) and the CLI returns an auth error (exit code 3). Re-run login with the domains you need — add --merge-scopes to keep the scopes you already have — see Authentication → Scope mapping:
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders,customers
A command returns an error envelope
Errors are printed to stderr as a structured envelope, usually with a hint (at an interactive terminal with pretty or table output you get a readable Error: / Hint: line instead):
{ "ok": false, "error": { "type": "auth", "message": "forbidden — your access token lacks the required scope", "hint": "Run 'shoplazza auth login' to re-authenticate. Use --domain or --scope to request the needed permission.", "detail": { "status_code": 403, "request_id": "req_abc123" } } }
Read the hint, and map the exit code to the failure type — see Exit codes. Include the request_id (under error.detail) when reporting an issue.
Not sure which parameters a command takes
Introspect the schema or use built-in help:
shoplazza schema products.create --view request
shoplazza products +search --help
Diagnosing the environment
shoplazza doctor check
doctor check covers the local config, credential directories, API metadata, and Agent Skills. It doesn't check your login — use shoplazza auth status for that.
Output is getting mixed into a pipe
Only stdout carries data (JSON); progress and warnings go to stderr. If a pipe looks corrupted, you are likely capturing stderr too — redirect it (2>/dev/null) or read the output conventions.