# Shoplazza CLI 排错

> 排查 Shoplazza CLI 的常见故障：命令找不到、令牌过期、作用域不足、错误信封、参数不明和管道输出被污染。

Shoplazza CLI 的常见问题及解决办法。智能体相关的问题见 [AI Toolkit 排错](/zh-CN/docs/app/developer-tools/ai-toolkit/troubleshooting)。

## `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 不足"报错

CLI 在每次调用前校验 OAuth scope。带上所需域重新登录——见[认证 → 作用域映射](./authentication#作用域映射):

```shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders,customers
```

## 命令返回错误信封

错误以结构化信封打印到 **stderr**,带 `hint`:

```json
{ "error": { "type": "api", "message": "Product not found", "hint": "Check the product ID and try again" }, "request_id": "req_abc123" }
```

读 `hint` 获知下一步,并把退出码对应到失败类型——见[退出码](./reference/exit-codes)。上报问题时带上 `request_id`。

## 不确定命令要哪些参数

内省 schema 或用内置 help:

```shell
shoplazza schema products.create --view request
shoplazza products +search --help
```

## 诊断环境

```shell
shoplazza doctor check
```

若你的版本尚无诊断,`shoplazza auth status` 是有用的兜底。

## 输出混进了管道

只有 **stdout** 承载数据(JSON);进度与警告走 **stderr**。若管道看起来乱了,多半是你把 stderr 也捕获了——重定向它(`2>/dev/null`)或参见[输出约定](./guides/output-formats#输出约定)。

## 参见

* [退出码](./reference/exit-codes)
* [错误格式](./reference/error-format)
* [全局 flag](./reference/global-flags)