# atmos artifacts inspect

Read an artifact's identity, kind, labels, documents, storage representation, and signature evidence without downloading its payload. Content and Record digests are labeled separately from the manifest or archive checksums, so each value says what it identifies.

> ⚠️ Experimental

## Usage

```shell
atmos artifacts inspect <ref> --repository=<alias> [flags]
```

## Examples

```shell
# Inspect a version
atmos artifacts inspect components/terraform/vpc:1.2.0 --repository=shared

# Machine-readable output
atmos artifacts inspect components/terraform/vpc:1.2.0 --repository=shared --format=json

# Inspect by digest
atmos artifacts inspect 'components/terraform/vpc@sha256:<digest>' --repository=shared
```

## Behavior

Inspect reads the Record and the storage descriptors only. Signature evidence that is present is listed as untrusted until it is verified. The `verification` value reports the trust outcome:

- **`unchecked`** — No trust policy applies, so nothing was verified. Catalog entries, labels, and earlier results never establish trust.
- **`verified`** — A trust policy applies and a valid permitted signature satisfied every trust set.
- **`failed`** — A trust policy applies and no permitted signature satisfied it. The command exits with a nonzero status.

## Arguments

- **`ref` (required)** — `name:version` or `name@sha256:<digest>`.

## Flags

- **`--repository`, `-r` (required)** — Configured repository alias.
  Environment variable: `ATMOS_ARTIFACTS_REPOSITORY`
- **`--format` (optional)** — Output format: `text` (default), `json`, or `yaml`.
  Environment variable: `ATMOS_ARTIFACTS_FORMAT`

## Output

Stdout carries `outcome` (`read`), `ref`, `location`, the four digests, and `size`, followed by `name`, `version`, `kind`, `created_at`, `description`, `labels`, the file count, document descriptors, `packaging`, the signature count, and `verification`. The structured result adds the full `inspection` (Record, representation, and evidence descriptors) and the `verification` result.

## Errors

- **Missing repository** — Exit code 2. The hint lists the configured aliases.
- **Malformed reference** — A reference without a version or digest fails: there is no implicit `latest`.
- **Not found** — The hint points to `atmos artifacts list`.
- **Verification failure** — A trust policy applies and no permitted signature satisfies it.

Every failure exits with a nonzero status. For failures reached while the command runs, `--format=json` or `--format=yaml` still writes the result to stdout with `outcome: failed` and an `error` field. Argument and flag parsing failures, such as a missing reference or an unknown flag, are rejected before the command runs and do not produce a structured result.

## Related

- [`atmos artifacts verify`](/cli/commands/artifacts/verify)
- [`atmos artifacts show`](/cli/commands/artifacts/show)
- [Artifacts Configuration](/cli/configuration/artifacts)