# 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

## Usage

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

## Examples

```shell
# 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

- [`atmos artifacts publish`](/cli/commands/artifacts/publish)
- [`atmos artifacts inspect`](/cli/commands/artifacts/inspect)
- [Artifacts Configuration](/cli/configuration/artifacts)