# atmos vendor update

Check each Git-backed source in your `vendor.yaml` for a newer version — honoring any
per-source constraints — and update the `version` field in place, preserving comments,
anchors, and Go templates such as `{{.Version}}` in source URLs.

## Usage

```shell
atmos vendor update [--check] [--pull] [--pull-request] [--group <name>] [--component <name>]... [--tags <a,b>] [--stack <stack>] [--labels <k>=<v>]... [--outdated] [--component-manifests]
```

Sources whose version is templated (`{{...}}`) or whose source is not a Git repository
are skipped and reported. Updates are written to the file that declares each source,
including imported manifests — a component declared in `vendor.yaml` has its
`spec.sources[].version` updated, while a component resolved from a per-component
`component.yaml` has its `spec.source.version` updated instead.

If `--component` isn't declared in `vendor.yaml` — or no `vendor.yaml` exists — Atmos falls
back to the component's own `component.yaml`/`component.yml` manifest, matching
`atmos vendor pull`'s existing precedence:
`vendor.yaml` wins whenever it declares the component. Without `--component`, a repo-wide
sweep of every `component.yaml` found under each component type's base path runs
automatically whenever no `vendor.yaml` exists — a repo that vendors exclusively via
`component.yaml` works with no extra flag. Add `--component-manifests` to also run that
sweep alongside an existing `vendor.yaml` (for repos that mix both manifest styles).

## Examples

```shell
# Dry run: show what would be updated.
atmos vendor update --check

# Update all Git-backed sources.
atmos vendor update

# Update versions and then pull the new components.
atmos vendor update --pull

# Update one or more components, or by tags.
atmos vendor update --component vpc
atmos vendor update --component vpc --component eks
atmos vendor update --tags networking,aws

# Update a named component, but only if its declared vendor.yaml source is also tagged.
atmos vendor update --component vpc --tags networking

# Update every component belonging to a stack, or matching stack metadata.labels.
# --stack/--labels resolve a component set (like `vendor pull --stack/--labels`); --tags
# is a separate, independent filter that composes with either of them, narrowing the
# resolved set to only components whose declared vendor.yaml source also matches.
atmos vendor update --stack dev-us-west-2
atmos vendor update --labels tier=1
atmos vendor update --stack dev-us-west-2 --labels tier=1
atmos vendor update --stack dev-us-west-2 --tags networking

# Repeat --labels to combine multiple selectors across occurrences.
atmos vendor update --labels tier=1 --labels cost-center=platform

# Show only sources with an available update.
atmos vendor update --check --outdated

# Also sweep per-component component.yaml manifests alongside an existing vendor.yaml.
atmos vendor update --check --component-manifests

# Commit, push, and open (or update) a pull request with available updates.
atmos vendor update --pull-request

# Only update the named vendor.update.groups selection, and open a pull request for it.
atmos vendor update --group platform --pull-request
```

See Native Pull Requests for Vendored Component Updates for the full `--pull-request` workflow (the Component Updater), including CI wiring.

The `--pull-request` flag authenticates to GitHub using `ATMOS_CI_GITHUB_TOKEN`, `ATMOS_PRO_GITHUB_TOKEN`, `GITHUB_TOKEN`, or `GH_TOKEN`, in that order. A PR opened with the default `GITHUB_TOKEN` won't trigger downstream `on: pull_request`/`on: push` Actions workflows. GitHub excludes its own default token from re-triggering workflows. To get a token that does trigger downstream workflows, pair the Component Updater with the [`github/sts`](/cli/configuration/auth#github-sts-atmos-pro) auth integration (see also Just-in-time GitHub tokens for CI with Atmos Pro STS). Run `atmos auth exec --identity <github-sts-identity> -- atmos vendor update --pull-request`. This mints a real GitHub App installation token and exports it as `ATMOS_PRO_GITHUB_TOKEN`. The Component Updater picks up this token automatically.

## Version constraints

Per-source constraints control which upstream versions are eligible:

```yaml
sources:
  - component: "vpc"
    source: "github.com/cloudposse/terraform-aws-components"
    version: "1.323.0"
    constraints:
      version: "^1.0.0"            # semver constraint (Masterminds/semver)
      excluded_versions:
        - "1.2.3"                  # a specific bad version
        - "1.5.*"                  # an entire broken series
      no_prereleases: true         # skip alpha/beta/rc
```

## Flags

- **`--check`**
  Dry run: show available updates without modifying any files.
- **`--pull`**
  After updating versions, run 
  `atmos vendor pull`
  .
- **`--all`**
  Update all discoverable vendor sources. This is the default when you give no 
  `--component`
  , 
  `--tags`
  , 
  `--group`
  , 
  `--stack`
  , or 
  `--labels`
   selector.
- **`--component` / `-c` (string, repeatable)**
  Update only these components. Repeat the flag to select more than one (
  `--component vpc --component eks`
  ). Cannot be combined with 
  `--stack`
  /
  `--labels`
  . Composes with 
  `--tags`
   (narrows to these components only if their declared 
  `vendor.yaml`
   tags also match).
- **`--tags` (string)**
  Update only components whose 
  `vendor.yaml`
   source declares any of these comma-separated tags. An independent filter: composes with 
  `--component`
   or 
  `--stack`
  /
  `--labels`
   to narrow further, or stands on its own.
- **`--stack` / `-s` (string)**
  Update only components belonging to the specified stack. Composes with 
  `--labels`
   to narrow further, and with 
  `--tags`
   to filter by declared source tags. Cannot be combined with an explicit 
  `--component`
  .
- **`--labels` (string, repeatable)**
  Update only components whose stack 
  `metadata.labels`
   match ALL of these 
  `key=value`
   or 
  `key:value`
   pairs — comma-separated within one occurrence, and/or repeated for more (
  `--labels tier=1 --labels cost-center=platform`
  ), resolved the same way as 
  `--stack`
  . Composes with 
  `--stack`
   and 
  `--tags`
  . Cannot be combined with an explicit 
  `--component`
  .
- **`--group` (string)**
  Update only the named 
  `vendor.update.groups`
   selection.
- **`--pull-request`**
  Commit, push, and create or update a pull request for the available updates. See 
  Native Pull Requests for Vendored Component Updates
  .
- **`--outdated`**
  Show only sources with an available update.
- **`--archived`**
  Show only sources whose upstream repository is archived.
- **`--format` (string, default `table`)**
  Output format: 
  `table`
   or 
  `json`
  .
- **`--type` / `-t` (string, default `terraform`)**
  Component type (
  `terraform`
  , 
  `helmfile`
  , or 
  `packer`
  ), used when falling back to a per-component 
  `component.yaml`
  , or to restrict a 
  `--component-manifests`
   sweep to one type.
- **`--component-manifests`**
  Also check per-component 
  `component.yaml`
   manifests when a 
  `vendor.yaml`
   is present (this sweep runs automatically when no 
  `vendor.yaml`
   exists). Only applies when 
  `--component`
   is not set.
- **`--file` (string, default `./vendor.yaml`)**
  The vendor manifest to start from (imports are followed).

These flags apply only together with `--pull`. Atmos passes them through to `atmos vendor pull`:

- **`--everything`**
  Pull all components, not just the ones that were updated.
- **`--dry-run`**
  Simulate the pull without writing any files.
- **`--refresh-lock`**
  Refresh immutable 
  `vendor.lock.yaml`
   entries from declared sources instead of failing on drift.
- **`--lock-enforcement` (string)**
  Override 
  `vendor.lock.enforcement`
   for this run: 
  `strict`
  , 
  `warn`
  , or 
  `silent`
  .

:::note
Version detection is supported for Git sources only (tags via `git ls-remote`), which
covers GitHub, GitLab, Bitbucket, and self-hosted Git. OCI, S3, GCS, and HTTP sources
are skipped. Private repositories are not yet supported.
:::

## Concurrent progress

Use `--max-concurrency N` to bound simultaneous downloads/preparation and upstream
checks. The default is four workers; [editions](/cli/configuration/edition) pinned
before `2026-09-15` retain one. Set `vendor.max_concurrency` in `atmos.yaml` or
`ATMOS_VENDOR_MAX_CONCURRENCY` for a persistent override. Explicit flags win over
environment and configuration. Values must be positive integers.

```shell
atmos vendor pull --max-concurrency 8
atmos vendor update --check --max-concurrency 8
atmos vendor update --pull --max-concurrency 8
```

The display identifies active packages, phases, retries, and available download
sizes. Downloads may finish in any order; destination writes remain ordered.
All editions use this display, including serial execution. Non-interactive runs
emit plain result lines to stderr. Update report formats on stdout are unchanged.

See [vendor concurrency configuration](/cli/configuration/vendor#concurrency)
for precedence, ordering, interruption, and shared-file coordination.