Skip to main content

atmos artifacts delete

Delete one published artifact reference, and the content it exclusively owns where the repository supports that. The command acts on exactly the reference you name and never prompts, so it is safe to run in CI.

Experimental
atmos artifacts delete --help

Usage​

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

Examples​

# Delete one published reference
atmos artifacts delete builds/app:build-123 --repository=backups

# Machine-readable result
atmos artifacts delete builds/app:build-123 --repository=backups --format=json

Behavior​

Delete resolves the reference once, takes the repository's write lock, and removes the pinned reference within the deletion scope the repository declares. It leaves other versions, the rest of the collection, and any catalog entry in place. On a registry, shared OCI blobs are subject to the registry's own garbage collection, and a registry that deletes by manifest digest also removes the other tags that point to that manifest.

The lock scope is reported as lock_scope. Local and OCI repositories lock at host scope by default; locking.repository delegates the lock to a coordinator repository.

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 (deleted), ref, location, the digests describing what was removed, size, and lock_scope. Stderr carries the status line.

Errors​

Missing repository
Exit code 2. The hint lists the configured aliases.
Malformed reference
A reference without a version or digest fails: there is no implicit latest.
Not found
The reference does not exist, including when it was already deleted.
Unsupported capability
The repository cannot delete, 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​