Shoplazza CLI 排错
Shoplazza CLI 的常见问题及解决办法。智能体相关的问题见 AI Toolkit 排错。
shoplazza: command not found
二进制不在 PATH 上。若用 npm 安装,确保全局 npm bin 目录在 PATH 上;若用 shell 脚本或二进制安装,默认装到 /usr/local/bin(make install 则为 ~/.local/bin)——把该目录加入 PATH。验证:
shell
shoplazza --version
认证失败或 token 过期
查看当前状态:
shell
shoplazza auth status
若 token 缺失或过期,重新认证:
shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders
"scope 不足"报错
token 缺少 scope 时,API 会拒绝调用(HTTP 403),CLI 返回 auth 错误(退出码 3)。带上所需域重新登录(加 --merge-scopes 可保留已有的 scope)——见认证 → 作用域映射:
shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders,customers
命令返回错误信封
错误以结构化信封打印到 stderr,通常带 hint(在交互式终端且输出为 pretty 或 table 时,改为打印易读的 Error: / Hint: 行):
json
{ "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" } } }
读 hint 获知下一步,并把退出码对应到失败类型——见退出码。上报问题时带上 request_id(位于 error.detail 下)。
不确定命令要哪些参数
内省 schema 或用内置 help:
shell
shoplazza schema products.create --view request
shoplazza products +search --help
诊断环境
shell
shoplazza doctor check
doctor check 检查本地配置、凭证目录、API 元数据和 Agent Skills,不检查登录状态——登录状态用 shoplazza auth status 查看。
输出混进了管道
只有 stdout 承载数据(JSON);进度与警告走 stderr。若管道看起来乱了,多半是你把 stderr 也捕获了——重定向它(2>/dev/null)或参见输出约定。