# 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

## Usage

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

## Examples

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

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