# Usage

## Install

```bash
curl -O https://inspired.jetskibay.com/inspired-cli/releases/1.0.0/inspired.mjs
chmod +x inspired.mjs
./inspired.mjs help
```

Put it on your `PATH` as `inspired` if you want to drop the `./` and the
extension. There is nothing to install and nothing to build: Node 20 or newer,
and the file.

```bash
node --version    # v20.0.0 or newer
```

## Authenticate

```bash
./inspired.mjs key new you@example.com    # mails you a key
export INSPIRED_KEY=isk_…                 # paste it from the email
./inspired.mjs key status
```

The key is only ever in that email — the platform stores its SHA-256 and
nothing else, so there is no "show me my key again". Losing it costs nothing:
minting for the same address revokes the old key and carries the remaining
allowance over.

`--key` overrides the environment for one call. `--base` points at another
deployment.

## A read, start to finish

```bash
./inspired.mjs shop outfit.jpg --out ./cutouts
```

```
started 3f0c8a5e-1d4b-4a9e-9a1c-2b8f5d7e6c40 · 9 request(s) left
waiting — a full read takes a few minutes
  Reading the look
  Cutting out the vest
  Searching for the vest
  …
wrote 5 files to ./cutouts
```

Then the report on stdout, and in `./cutouts`:

```
mood-board.webp          the cutouts composed into one square image
piece-1-vest.webp        one product shot per object
piece-2-shirt.webp
result.json              the API payload, verbatim
```

Progress lines go to **stderr** and the report to **stdout**, so
`./inspired.mjs shop outfit.jpg --json > result.json` works and still shows you
progress.

## Choosing what to look for

```bash
./inspired.mjs domains                                   # free, no key
./inspired.mjs shop desk.jpg --domain devices
./inspired.mjs shop shed.jpg --domain everything --focus "power tools only"
```

The default is `fashion`, which is the wrong subject for most non-outfit
photos — pass `--domain` explicitly. An unknown domain is refused by the server
before anything is charged.

## Not waiting

For a slow read, or from a script:

```bash
ID=$(./inspired.mjs start living-room.jpg --domain furniture)
# … go and do something else …
./inspired.mjs get "$ID" --out ./cutouts
```

`start` prints only the request id on stdout, so it is safe to capture.
`get` looks once and exits; it never polls. Both are free except for the `start`
itself.

If `shop` gives up waiting it tells you the id, which stays valid. Collect it
later rather than starting again — starting again is another request.

## Pinterest

```bash
./inspired.mjs shop 'https://www.pinterest.com/pin/1234567890/'
```

Quote the URL. If Pinterest refuses to share the pin's preview, screenshot the
pin and pass the file instead.

## Exit codes and errors

`0` on success, `1` on anything else, with the server's own message and error
code on stderr. The ones worth scripting against:

| Message contains | Means | Do |
| --- | --- | --- |
| `quota_exhausted` | The key's requests are used up | Stop. Do not mint another key to get around it. |
| `expired_api_key` | Past its 24 hours | `key new` |
| `Request not found` | Wrong id, or another key's read | Check the id; do not retry |
| `Still running after N minutes` | Slow, not broken | `get <id>` later |
| `is N MB. The limit is 10 MB` | Refused locally, nothing charged | Resize it |

## Reading the report

```
vest
  soft navy knitted vest with a V neckline and ribbed armholes
  €39      Knitted V-neck vest, navy
           https://shop.example/knitted-vest
```

The description is what the reader could actually see. The rows under it are
what visual search returned for that cutout, in its own price-led order — the
client does not re-sort them, because there is no similarity score in the
response to sort by.

The last line of every report says it out loud: objects are spotted, not
identified, and results are visually similar, not the same product.