# atmos vendor clean

Remove every vendored file recorded in `vendor.lock.yaml`. Only deletes files the lock actually
owns. It never deletes files another still-selected artifact owns, and never deletes files outside
the lock entirely.

## Usage

```shell
atmos vendor clean [--component <name>] [--tags <a,b>] [--force] [--dry-run] [--prune-lock]
atmos vendor clean [--stack <stack>] [--labels <k>=<v>] [--tags <a,b>] [--force] [--dry-run] [--prune-lock]
```

By default, `vendor clean` preserves any lock-owned file whose content doesn't match its recorded
checksum. It refuses to run and names every such file. Pass `--force` to delete them anyway.
`vendor clean` preserves `vendor.lock.yaml` and all its entries, including recorded versions,
checksums, and provenance. This also applies to selective cleanup and `--force`. A subsequent
`vendor pull` reinstalls a fully cleaned package without missing-file drift warnings, using
the retained lock information. Partially missing or modified files still trigger drift checks; use
`vendor pull --refresh-lock` when you intend to refresh the lock.

To **permanently** remove a component — not just its files — pass `--prune-lock` to also forget the
cleaned components' lock entries. Use it when you've removed (or are about to remove) the source
from `vendor.yaml`: without it, the orphaned lock entry keeps its recorded files, which
`vendor verify` then reports as missing. `--prune-lock` only forgets the entries the same selectors
matched, so it never touches entries you didn't target.

At most one base selector may be given: `--component` or `--stack`/`--labels` (a stack-resolved
component set, composable with each other, like
`atmos vendor pull`'s own `--stack`/`--labels`). `--tags`
(vendor.yaml's own declared source tags) is a separate, independent filter that composes with
either base selector, or stands on its own — narrowing the cleaned set to only components whose
declared tags also match; a component with no `vendor.yaml` entry has no tags to match and is
excluded by a non-empty `--tags` filter. Omit every selector to clean everything. A selector that
matches nothing is an error, not a silent "clean everything" fallback.

## Examples

```shell
# Preview what would be removed, without deleting anything.
atmos vendor clean --dry-run

# Remove every vendored artifact recorded in the lock.
atmos vendor clean

# Remove only one component's vendored files.
atmos vendor clean --component vpc

# Remove every component whose vendor.yaml source declares a given tag.
atmos vendor clean --tags networking

# Remove every component in a stack, or matching stack metadata.labels.
atmos vendor clean --stack dev-us-west-2
atmos vendor clean --labels tier=1

# Combine multiple selectors in one comma-separated --labels value.
atmos vendor clean --labels tier=1,cost-center=platform

# Remove a stack's components, narrowed further by declared vendor.yaml tags.
atmos vendor clean --stack dev-us-west-2 --tags networking

# Delete lock-owned files even if they were modified since vendoring.
atmos vendor clean --force

# Permanently remove a component: delete its files AND forget its lock entry,
# then remove its source from vendor.yaml (no orphan left for `vendor verify`).
atmos vendor clean --component vpc --prune-lock
```

## Flags

- **`--component` / `-c` (string)** — Clean only this component. Mutually exclusive with `--stack`/`--labels`. Composes with `--tags` (narrows to this component only if its declared `vendor.yaml` tags also match).
- **`--tags` (string)** — Clean only components whose `vendor.yaml` source declares any of these comma-separated tags (matches any). An independent filter: composes with `--component` or `--stack`/`--labels` to narrow further, or stands on its own.
- **`--stack` / `-s` (string)** — Clean only components belonging to the specified stack. Composes with `--labels` to narrow further, and with `--tags` to filter by declared source tags. Mutually exclusive with `--component`.
- **`--labels` (string)** — Clean only components whose stack `metadata.labels` match ALL of these `key=value` or `key:value` pairs — comma-separated in one flag value (`--labels tier=1,cost-center=platform`). Composes with `--stack` and `--tags`. Mutually exclusive with `--component`.
- **`--type` / `-t` (string, default `terraform`)** — Component type (`terraform`, `helmfile`, or `packer`). Pass this flag explicitly to scope a `--stack`/`--labels` selection to one component type. When you omit it, every component type is considered.
- **`--file` (string, default `./vendor.yaml`)** — The vendor manifest to read declared source tags from when resolving `--tags`.
- **`--force` (boolean)** — Delete modified lock-owned files instead of refusing to run.
- **`--dry-run` (boolean)** — Show which files would be removed without deleting anything. Combined with `--prune-lock`, also shows which lock entries would be forgotten.
- **`--prune-lock` (boolean)** — Also remove the cleaned components' entries from `vendor.lock.yaml`, so a source removed from `vendor.yaml` no longer leaves an orphan entry that `vendor verify` reports as missing. Only the entries the selectors matched are forgotten. Default: entries are preserved.

:::note
A single modified file blocks the entire run unless you pass `--force`. Atmos deletes no files for
that invocation, even unmodified ones, until you resolve the conflict or pass `--force`. Scope with
`--component` to clean only the artifacts you're sure about.
:::