Skip to main content

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
atmos artifacts verify --help

Usage​

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

Examples​

# 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​