# atmos artifacts verify

Check an artifact's stored signature evidence against your trust policy. Verify always requires a trusted, valid signature, so a successful exit means the artifact was signed by a signer you trust.

> ⚠️ Experimental

## Usage

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

## Examples

```shell
# Require a trusted valid signature
atmos artifacts verify components/terraform/vpc:1.2.0 --repository=shared

# Machine-readable result
atmos artifacts verify components/terraform/vpc:1.2.0 --repository=shared --format=json
```

## Behavior

Verify authenticates the evidence stored for the artifact's signed subject (the Record, or the original OCI root of a foreign graph) against the effective policy. The policy combines the global `artifacts.verification` trust set with the repository's own; when both exist, both must be satisfied rather than merged into a weaker policy. Within one trust set, any configured signer can satisfy it.

The check covers the subject binding, the cryptographic validity, the signer identity or key, and the certificate, transparency log, and signing-time proofs. Evidence that is invalid, unrelated, or in an unsupported format is reported with bounded diagnostics and never overrides valid matching evidence. Unsupported required evidence fails closed.

When no trusted identities or keys are configured, nothing can be verified. The command fails with `verification` status `unchecked` and a hint to configure `artifacts.verification`; it never reports success. Catalog entries, labels, and cached results never count as trust.

## 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 digests, `verification` status (`verified`, `unchecked`, or `failed`), the verified `subject`, the policy fingerprint, and one `signer` line per verified claim. The structured result carries the full `verification` result: subject, policy fingerprint, claims, evidence digests, status, and diagnostics.

## Errors

- **Missing repository** — Exit code 2. The hint lists the configured aliases.
- **No trust configured** — Fails with status `unchecked` and a hint to set `artifacts.verification.trusted_identities` or `trusted_keys`.
- **No permitted signature** — Fails with an artifact signature verification error when the evidence is missing, invalid, or signed by a signer that is not trusted.
- **Unsupported capability** — The repository cannot verify evidence for this subject kind.

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. The `verification` result is included only when verification ran far enough to produce one, such as an `unchecked` or `failed` status. Failures that happen first, such as a missing repository, an unresolvable reference, or an unavailable service, carry no `verification` field, so check for its presence before reading it. 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 sign`](/cli/commands/artifacts/sign)
- [`atmos artifacts inspect`](/cli/commands/artifacts/inspect)
- [Artifacts Configuration](/cli/configuration/artifacts)