Skip to main content

atmos artifacts show

Read the README or CHANGELOG that ships with an artifact, straight from its stored Record. Only the document is fetched, so you can read what a package contains before you pull it.

Experimental
atmos artifacts show --help

Usage​

atmos artifacts show readme <ref> --repository=<alias> [flags]
atmos artifacts show changelog <ref> --repository=<alias> [flags]

Examples​

# Show the README of an artifact
atmos artifacts show readme components/terraform/vpc:1.2.0 --repository=shared

# Show the CHANGELOG of an artifact
atmos artifacts show changelog components/terraform/vpc:1.2.0 --repository=shared

# Save a document
atmos artifacts show readme components/terraform/vpc:1.2.0 --repository=shared > README.md

# Document text and descriptor as JSON
atmos artifacts show changelog components/terraform/vpc:1.2.0 --repository=shared --format=json

Behavior​

Package documents come from the reserved .atmos/artifact/ directory of the published source, or from the paths given to --readme and --changelog at publish time. Show verifies the document bytes against the digest in the Record and enforces a size limit. The payload is never downloaded.

Subcommands​

readme
Show the README of the artifact.
changelog
Show the CHANGELOG of the artifact.

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. The text format prints the document verbatim. Environment variable: ATMOS_ARTIFACTS_FORMAT

Output​

With the text format, stdout carries the document exactly as published, so it can be piped or redirected. Stderr carries diagnostics only. The json and yaml formats return the standard result fields plus the document descriptor (role, source path, media type, size, and digest) and the document content.

Errors​

Missing repository
Exit code 2. The hint lists the configured aliases.
Missing document
The artifact was published without that document. Fails with an artifact document not found error.
Not found
The reference does not exist in the repository.
Malformed reference
A reference without a version or digest fails: there is no implicit latest.

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​