# Image Inspection Guide

## Overview

`stella image inspect` resolves an OCI image reference, enumerates platform manifests, and lists layers. Use it to confirm what is deployed where and to feed downstream verification workflows.

## Basic usage

```bash
stella image inspect nginx:latest
```

## JSON output for automation

```bash
stella image inspect nginx:latest --output json > image-inspect.json
```

## Platform filter

```bash
stella image inspect nginx:latest --platform linux/amd64
```

## Private registry (HTTP)

For local registries that use HTTP, include the scheme in the reference:

```bash
stella image inspect http://localhost:5000/myapp:1.0.0
```

If you need registry auth, configure the `OciRegistry` section in your CLI config (see `docs/modules/scanner/image-inspection.md`).

## CI usage example

```bash
stella image inspect ghcr.io/org/app:1.2.3 --output json \
  | jq '.platforms[] | { os: .os, arch: .architecture, layers: (.layers | length) }'
```

## Troubleshooting

### Authentication required
- Symptom: `Authentication required` error.
- Fix: configure `OciRegistry.Auth` in your CLI config or use a registry that allows anonymous pulls.

### Rate limits
- Symptom: HTTP 429 or warnings about rate limits.
- Fix: retry later, use authenticated credentials, or mirror to a private registry.

### Unsupported media types
- Symptom: warnings about unknown manifest media types.
- Fix: confirm the registry serves OCI or Docker v2 manifests, and ensure the image reference is correct.