# docs

> Use shoplazza docs to search the Shoplazza developer docs — guides and API reference — and read any page as Markdown.

Search the developer docs on [shoplazza.dev](https://www.shoplazza.dev) and read a page as Markdown, straight from the terminal. It covers the app and theme guides and the API reference for every API version, in English and Chinese.

`docs` and [`schema`](./schema) answer different questions. `schema` works offline and shows the flags, request body, and response of a CLI command, based on the API spec built into the CLI. `docs` searches the online docs for concepts, flows, field meanings, and business rules.

## search

Search the docs and return the best-matching pages.

```shell
shoplazza docs search --query <keywords> [flags]
```

### Flags

| Flag | Type | Description |
|------|------|-------------|
| `--query <keywords>` | string | **Required.** What to search for. Keep it short and include the API or field name, e.g. `"webhook HMAC verification"`, rather than a whole question |
| `--locale <en\|zh-CN>` | string | Language of the docs to search. Default: `zh-CN` when the query contains Chinese characters, otherwise `en` |
| `--api-version <version>` | string | API version of the API reference results, e.g. `202601` or `2026-01`. Default: the site's default version (currently `202607`) |
| `--limit <n>` | number | Number of results, 1–20 (default: `5`) |

### Output

With `--format json`, `data` holds the locale searched and the results, best match first. Each result is one page:

```json
{
  "locale": "en",
  "results": [
    {
      "url": "https://www.shoplazza.dev/docs/app/building-blocks/authentication/oauth-flow",
      "title": "OAuth authentication",
      "content": "<the matching section of the page, as Markdown>",
      "score": 0.86
    },
    {
      "url": "https://www.shoplazza.dev/api/order-cancel",
      "title": "Cancel order",
      "content": "{\"operationId\":\"order-cancel\",\"method\":\"POST\",\"path\":\"/openapi/2026-07/orders/{order_id}/cancel\",…,\"part\":\"request\",\"fields\":{…}}",
      "score": 0.81
    }
  ]
}
```

| Field | Description |
|-------|-------------|
| `url` | Full page URL. Pass it to [`docs get`](#get) to read the whole page |
| `title` | Page title; for API reference pages, the endpoint summary |
| `content` | The best-matching section of the page. Often enough to answer without `docs get` |
| `score` | Relevance, 0–1 |

With `--format ndjson`, each result prints as one line. When nothing matches, the command exits `0` with `results: []` and prints a hint on stderr; try different keywords.

### Examples

```shell
# Search the English docs
shoplazza docs search --query "webhook HMAC verification"

# Search the Chinese docs (picked automatically from the query)
shoplazza docs search --query "应用订阅计费"

# Search the API reference of the version the CLI commands are built on
shoplazza docs search --query "cancel order" --api-version 202601 --limit 3
```

## get

Read one page as Markdown.

```shell
shoplazza docs get --url <url|path> [flags]
```

### Flags

| Flag | Type | Description |
|------|------|-------------|
| `--url <url\|path>` | string | **Required.** A `https://www.shoplazza.dev/...` URL or a site path such as `/docs/app/...` or `/zh-CN/api/...`. Anchors (`#...`), query strings, and a trailing `.md` or `/` are ignored. URLs on other domains are rejected |
| `--max-chars <n>` | number | Maximum characters of Markdown to return (default: `20000`). A longer page is cut at the last line break before the limit |
| `--output <file>` | string | Write the whole page to a file instead, without the length limit |

The page language comes from the URL: paths under `/zh-CN/` are Chinese.

### Output

* At an interactive terminal (`pretty`), the command prints the page's Markdown as is.
* With `--format json` (the default for agents and pipes), `data` is:

| Field | Description |
|-------|-------------|
| `url` | Final page URL, after redirects |
| `title` | The page's first heading |
| `locale` | `en` or `zh-CN` |
| `markdown` | The page content, up to `--max-chars` characters |
| `total_chars` | Length of the whole page, even when `markdown` is cut |
| `truncated` | `true` when `markdown` was cut; stderr then suggests `--output` or a larger `--max-chars` |

* With `--output`, `data` is `{url, title, locale, file, total_chars}` and holds no content.

### Examples

```shell
# Read a guide
shoplazza docs get --url https://www.shoplazza.dev/docs/app/building-blocks/authentication/oauth-flow

# Read an API reference page of a specific version, by path
shoplazza docs get --url /api/202601/order-cancel

# Save a long page to a file
shoplazza docs get --url /docs/theme/references/liquid --output liquid.md
```

## Errors

`docs` errors use the standard [error envelope](../reference/error-format) and [exit codes](../reference/exit-codes):

| Situation | Type (exit code) | Other fields |
|-----------|------------------|--------------|
| Invalid flag value, e.g. an unknown `--api-version` | `validation` (2) | `subtype`: `invalid_flag_value` |
| Search service unreachable or timed out (30 s) | `network` (4) | — |
| Too many requests | `api` (1) | `code`: `rate_limited`, `detail.status_code`: `429` |
| The page does not exist, e.g. it was removed | `api` (1) | `detail.status_code`: `404` |
| Search service error | `api` (1) | `detail.status_code`: `5xx` |

The command does not retry on its own.