# Command-line interface

Installing iiisight registers an **`iiisight`** command — a thin, dependency-free
front-end over the library (stdlib `argparse`, no extra needed):

```console
$ iiisight --version
$ iiisight lint https://example.org/manifest.json
$ iiisight info manifest.json
$ iiisight tiles https://example.org/manifest.json --scale 4
```

Every command accepts either a **URL** (fetched over HTTP) or a path to a **local
JSON file**.

## `iiisight lint`

Report what a client had to repair to read a document — a reporting view over the
normalization diagnostics (see [Tolerance & diagnostics](tolerance.md)).

```console
$ iiisight lint https://example.org/manifest.json
1 error(s), 2 warning(s), 0 info
  warning coerced-language-map /label
          Expected a language map object but found a bare string.
  error   image-service-missing-id /items/0/.../service/0
          Image service has no id; image URLs cannot be built.
```

- Exits **non-zero when there are errors**, so it works in CI (`--strict` also
  fails on warnings).
- `--json` emits a machine-readable report.

```console
$ iiisight lint manifest.json --json
{
  "ok": false,
  "summary": "1 error(s), 2 warning(s), 0 info",
  "diagnostics": [ ... ]
}
```

## `iiisight info`

Summarize a manifest or collection.

```console
$ iiisight info https://example.org/manifest.json
Manifest  https://example.org/manifest
  label: Picture of Göttingen
  canvases: 1
    [0] 3024x4032  1 image(s)  service=https://example.org/iiif/image
  diagnostics: 0
```

`--json` emits the same summary as structured data.

## `iiisight tiles`

Load a manifest's first image service (fetching its `info.json`) and print the
computed tile URLs. Requires a URL.

```console
$ iiisight tiles https://example.org/manifest.json --scale 4 --thumbnail 300
https://example.org/iiif/image
  6000x4000  level1  api v3
  thumbnail: https://example.org/iiif/image/full/375,/0/default.jpg
  tiles (scaleFactor=4):
    https://example.org/iiif/image/0,0,2048,2048/512,/0/default.jpg
    ...
```

- `--scale N` picks the scale factor (default: a middle advertised one).
- `--thumbnail WIDTH` also prints a thumbnail URL.

## `iiisight probe`

Check an image service for Image API conformance — see
[Image API conformance](conformance.md). Requires a URL.

```console
$ iiisight probe https://example.org/iiif/image
https://example.org/iiif/image  claimed: level2
  PASS  full image     got 6000x4000, expected ~6000x4000
  FAIL  regionByPx     got 6000x4000, expected ~3000x2000
  ...
4/6 checks passed; does NOT conform to level2
```

Exits `0` when the service conforms, `1` when it doesn't. `--json` for the full
report.

## `iiisight changes`

List recent activities from a [Change Discovery](discovery.md) stream (newest
first). Requires a URL.

```console
$ iiisight changes https://example.org/activity/all-changes --limit 20
2024-03-01T09:00:00Z      Update    https://example.org/iiif/book1/manifest
2024-02-28T12:30:00Z      Create    https://example.org/iiif/book2/manifest
...
```

`--since <endTime>` limits to newer activities; `--limit N` stops after N.

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | success (and, for `lint`/`probe`, no problems that fail the run) |
| `1` | `lint` found errors (or warnings with `--strict`); `probe` found non-conformance |
| `2` | an error occurred (bad file, fetch failure, wrong document type) |