Skip to main content

atmos artifacts copy

Copy an artifact from one configured repository to another while preserving its identity, metadata, documents, and verified content. Use it to promote a build from a working repository to a shared one, or to back up between different storage kinds.

Experimental
atmos artifacts copy --help

Usage​

atmos artifacts copy <ref> --from=<alias> --to=<alias> [flags]

Examples​

# Copy an artifact from one repository to another
atmos artifacts copy components/terraform/vpc:1.2.0 --from=shared --to=backups

# Replace a conflicting destination
atmos artifacts copy components/terraform/vpc:1.2.0 --from=shared --to=backups --force

Behavior​

The artifact keeps its name, version, kind, labels, and Record. The destination may change the physical representation: copying from a local/dir repository to a local/archive repository packs the payload, and the representation_digest differs while record_digest and content_digest stay the same. Destination label defaults do not restamp a copy.

Atmos uses a backend-native transfer when both sides support one and otherwise streams through bounded staging. Both the source and the destination verification policy are evaluated, and the evidence each one needs is retained. --force replaces a conflicting destination but never bypasses verification, and never replaces a plugin release.

Writes to the destination take that repository's lock, reported as lock_scope.

Arguments​

ref (required)

name:version or name@sha256:<digest> in the source repository.

Flags​

--from (required)

Source repository alias. Environment variable: ATMOS_ARTIFACTS_FROM

--to (required)

Destination repository alias. Environment variable: ATMOS_ARTIFACTS_TO

--force, -f (optional)

Replace a conflicting destination. Environment variable: ATMOS_ARTIFACTS_FORCE

--format (optional)

Output format: text (default), json, or yaml. Environment variable: ATMOS_ARTIFACTS_FORMAT

Output​

Stdout carries outcome (created, unchanged, or replaced), ref, location in the destination, the digests, size, and lock_scope. Stderr carries the status line.

Errors​

Missing --from or --to
Exit code 2, with a hint that names the flag and its environment variable.
Unknown alias
Fails with an invalid artifact configuration error that lists the configured aliases.
Not found
The reference does not exist in the source repository.
Conflict
The destination holds different content at the same reference. Re-run with --force.
Verification failure
Source or destination policy requires a signature that is missing or untrusted. Nothing is written to the destination.
Unsupported capability
The destination is read-only, or cannot provide the required lock scope.

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​