# Shoplazza CLI troubleshooting

> Fix common Shoplazza CLI failures: command not found, expired tokens, insufficient scope, error envelopes, unknown parameters, and output polluting a pipe.

Common issues with Shoplazza CLI and how to resolve them. For AI-agent-specific issues, see the [AI Toolkit troubleshooting](/docs/app/developer-tools/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:

```shell
shoplazza version
```

## Authentication fails or a token expired

Check your current state:

```shell
shoplazza auth status
```

Re-authenticate if the token is missing or expired:

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

## "Insufficient scope" errors

The CLI checks OAuth scopes before each call. Re-run login with the domains you need — see [Authentication → Scope mapping](./authentication#scope-mapping):

```shell
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 with a `hint`:

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

Read the `hint`, and map the exit code to the failure type — see [Exit codes](./reference/exit-codes). Include the `request_id` when reporting an issue.

## Not sure which parameters a command takes

Introspect the schema or use built-in help:

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

## Diagnosing the environment

```shell
shoplazza doctor check
```

If diagnostics aren't available in your version, `shoplazza auth status` is a useful fallback.

## 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](./guides/output-formats#output-conventions).

## See also

* [Exit codes](./reference/exit-codes)
* [Error format](./reference/error-format)
* [Global flags](./reference/global-flags)