> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychannel3.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating to 0.5.0

CLI `0.5.0` replaces the binary that shipped through `0.4.1`. The command shape
(`channel3 <resource> <command>`), the binary name, and `CHANNEL3_API_KEY` are
unchanged — but installation moved to npm and several flags changed.

## 1. Reinstall

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
brew uninstall --cask channel3
npm install -g @channel3/cli
```

Confirm you're on the new one:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
channel3 --version    # 0.5.0
which channel3        # should be your npm prefix, not /opt/homebrew/bin
```

Homebrew no longer receives updates, and `go install` is gone.

## 2. Rename `--query` — the one that bites

`--query` still exists, but it means something entirely different: it is now a
[JMESPath](https://jmespath.org) projection applied to the response. The search
term moved to `--query-param`.

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
# before
channel3 products search --query "running shoes"
# after
channel3 products search --query-param "running shoes"
```

Left unchanged, a multi-word search fails with a JMESPath parse error. A
single-word search is worse: `--query shoes` is *valid* JMESPath, so no search
term is sent and you get back `null` or a 422.

## 3. Flag changes

| Up to 0.4.1                           | 0.5.0                                    | Notes                                             |
| ------------------------------------- | ---------------------------------------- | ------------------------------------------------- |
| `--query`                             | `--query-param`                          | The search term. See above.                       |
| `--transform` (GJSON)                 | `--query` (JMESPath)                     | `.#.` becomes `[]`; keys need explicit names      |
| `--max-items N`                       | `--limit N`                              | See pagination below                              |
| `--format pretty`                     | `--format table`                         |                                                   |
| `--format auto`                       | *(default)*                              | Table at a terminal, JSON when piped              |
| `--format explore`                    | *(none)*                                 | The interactive browser has no replacement        |
| `--format-error`, `--transform-error` | *(none)*                                 | Errors can't be formatted or projected separately |
| `--base64-image @file.jpg`            | `--base64-image "$(base64 -i file.jpg)"` | `@path` is no longer expanded                     |

`--format jsonl`, `--format raw`, `--debug`, `--base-url` and `--api-key` are
unchanged. New: `--dry-run`, `--page-all`, `--quiet`, `--schema`, `--spec`,
`csv` and `http` output formats, `auth` for keyring-stored credentials, and
`completion` for shell completions.

## 4. Pagination inverted

Up to `0.4.1` the CLI auto-paginated, and `--max-items` existed to rein it in.
`0.5.0` returns a **single page** unless you ask for more:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
channel3 products search --query-param "socks" --limit 20          # one page
channel3 products search --query-param "socks" --page-all --page-limit 3
```

If your scripts passed `--max-items` defensively, you can usually just drop it
and set `--limit`.

<Note>
  `--page-all` emits one JSON object **per page**, each containing a `products`
  array — not one object per product. To iterate products across pages, unwrap
  them yourself:

  ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
  channel3 products search --query-param "socks" --page-all --format jsonl \
    | jq -c '.products[]'
  ```

  Combining `--page-all` with `--query` is not recommended: the projection is
  applied to each page wrapper before the output is flattened, which makes
  expressions behave differently than they do on a single-page call. Project
  with `--query` on single-page calls, and use `jq` when paginating.
</Note>

## 5. Translate your projections

`--transform` used GJSON; `--query` uses JMESPath.

| GJSON                                                              | JMESPath                                                                                   |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `products.#.title`                                                 | `products[].title`                                                                         |
| `products.0.offers.0.price`                                        | `products[0].offers[0].price`                                                              |
| `brands.#.{id,name}`                                               | `brands[].{id: id, name: name}`                                                            |
| `products.#.{id,title,offers:offers.#.{domain,price:price.price}}` | `products[].{id: id, title: title, offers: offers[].{domain: domain, price: price.price}}` |

Two rules cover most cases: `.#.` becomes `[]`, and JMESPath has no shorthand
for `{id}` — every key needs `name: path`.

Note that projections now start at the response wrapper (`products[]`,
`brands[]`, `categories[]`), because `--query` applies to the whole response
before `--format jsonl` flattens it.

## 6. Commands that moved

| Removed                      | Use instead                |
| ---------------------------- | -------------------------- |
| `channel3 search perform`    | `channel3 products search` |
| `channel3 enrich enrich-url` | `channel3 products lookup` |
| `channel3 brands find`       | `channel3 brands search`   |

New in 0.5.0: `products browse`, `products monetize`, `reporting list-clicks`,
`reporting list-transactions`, and `conversations` with its `client-tokens`
sub-resource.

## Using the CLI from an agent

If you installed the Channel3 skills, update them too — they call the CLI
directly and the old flags fail at runtime:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx skills add channel3-ai/skills --skill product-discovery
```