# atmos vendor pull

This command implements [Atmos Vendoring](/vendor/). Use this command to download sources from local and remote
repositories for Terraform and Helmfile components and stacks.

_\[Video: atmos vendor pull]_

With Atmos vendoring, you can copy components and other artifacts from the following sources:

- Copy all files from an [OCI Registry](https://opencontainers.org) into a local folder
- Copy all files from Git, Mercurial, Amazon S3, Google GCP into a local folder
- Copy all files from an HTTP/HTTPS endpoint into a local folder
- Copy a single file from an HTTP/HTTPS endpoint to a local file
- Copy a local file into a local folder (keeping the same file name)
- Copy a local file to a local file with a different file name
- Copy a local folder (all files) into a local folder

## Usage

Execute the `vendor pull` command like this:

```shell
atmos vendor pull
atmos vendor pull --everything
atmos vendor pull --component <component> [options]
atmos vendor pull -c <component> [options]
atmos vendor pull --tags <tag1>,<tag2> [options]
```

## Description

Atmos supports two different ways of vendoring components, stacks and other artifacts:

- Using `component.yaml` vendoring manifest
- Using `vendor.yaml` vendoring manifest

The `component.yaml` vendoring manifest can be used to vendor components from remote repositories.
A `component.yaml` file placed into a component's directory is used to describe the vendoring config for one component only.
Using `component.yaml` is not recommended, and it's maintained for backwards compatibility.

The `vendor.yaml` vendoring manifest provides more functionality than using `component.yaml` files.
It's used to describe vendoring config for all components, stacks and other artifacts for the entire infrastructure.
The file is placed into the directory from which the `atmos vendor pull` command is executed. It's the recommended way to describe vendoring
configurations.

## Vendoring using `vendor.yaml` manifest

- The `vendor.yaml` vendoring manifest supports Kubernetes-style YAML config to describe vendoring configuration for components, stacks,
  and other artifacts.

- The `source` attribute supports all protocols (local files, Git, Mercurial, HTTP, HTTPS, Amazon S3, Google GCP), and all URL and
  archive formats as described in [go-getter](https://github.com/hashicorp/go-getter), and also the `oci://` scheme to download artifacts from
  [OCI registries](https://opencontainers.org). See [Vendor URL Syntax](/vendor/url-syntax) for complete documentation on supported URL formats and authentication.

- The `targets` in the `sources` support absolute paths and relative paths (relative to the `vendor.yaml` file). Note: if the `targets` paths
  are set as relative, and if the `vendor.yaml` file is detected by Atmos using the `base_path` setting in `atmos.yaml`, the `targets` paths
  will be considered relative to the `base_path`. Multiple targets can be specified.

- `included_paths` and `excluded_paths` support [POSIX-style greedy Globs](https://en.wikipedia.org/wiki/Glob_\(programming\)) for filenames/paths
  (double-star/globstar `**` is supported as well).

- The `tags` in each source specifies a list of tags to apply to the component. This allows you to only vendor the components that have the
  specified tags by executing a command `atmos vendor pull --tags <tag1>,<tag2>`

:::tip
Refer to [`Atmos Vendoring`](/vendor/) for more details
:::

## Vendoring using `component.yaml` manifest

- The `component.yaml` vendoring manifest supports Kubernetes-style YAML config to describe component vendoring configuration.
  The file is placed into the component's folder.

- The URIs (`uri`) in `component.yaml` support all protocols (local files, Git, Mercurial, HTTP, HTTPS, Amazon S3, Google GCP), and all URL and
  archive formats as described in [go-getter](https://github.com/hashicorp/go-getter), and also the `oci://` scheme to download artifacts from
  [OCI registries](https://opencontainers.org).

- `included_paths` and `excluded_paths` in `component.yaml` support [POSIX-style greedy Globs](https://en.wikipedia.org/wiki/Glob_\(programming\)) for
  file names/paths (double-star/globstar `**` is supported as well).

:::tip
Refer to [`Atmos Component Vendoring`](/vendor/component-manifest) for more details
:::

## Vendoring from OCI Registries

The following config can be used to download the `vpc` component from an AWS public ECR registry:

```yaml
apiVersion: atmos/v1
kind: ComponentVendorConfig
metadata:
  name: vpc-vendor-config
  description: Config for vendoring of 'vpc' component
spec:
  source:
    # Download the component from the AWS public ECR registry (https://docs.aws.amazon.com/AmazonECR/latest/public/public-registries.html)
    uri: "oci://public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:{{.Version}}"
    version: "latest"
```

## Vendoring from SSH

Atmos supports SSH for accessing non-public Git repositories, which is convenient for local development. Atmos will use any installed SSH keys automatically.

:::tip
In automated systems like GitHub Actions, we recommend sticking with the `https://` scheme for vendoring. Atmos will automatically inject the `GITHUB_TOKEN`.
:::

There are two primary ways to specify an SSH source.

### SCP-style Sources

Atmos supports traditional SCP-style sources, which use a colon to separate the host from the repository, like this:

```shell
git::git@github.com:cloudposse/terraform-null-label.git?ref={{.Version}}
```

Atmos rewrites this URL to the following format:

```shell
git::ssh://git@github.com/cloudposse/terraform-null-label.git?depth=1&ref={{.Version}}
```

If no username is supplied and the host is `github.com`, Atmos automatically injects the default username `git`.

### Explicit SSH Sources

When the `ssh://` scheme is explicitly specified, the URL is used as provided, and no rewriting occurs.

For example:

```shell
git::ssh://git@github.com/cloudposse/terraform-null-label.git?ref={{ .Version }}
```

### Important Notes

- The following URL is **invalid** because `go-getter` misinterprets `github.com:` as a URL scheme (like `http:` or `git:`), causing a parsing error:
  ```shell
  github.com:cloudposse/terraform-null-label.git?ref={{ .Version }}
  ```

- When a URL has no scheme, Atmos defaults to **HTTPS** and injects credentials if available.
  ```shell
  github.com/cloudposse/terraform-null-label.git?ref={{ .Version }}
  ```

## Git over HTTPS Vendoring

Atmos supports vendoring components using **Git over HTTPS**.

For example:

```
github.com/cloudposse/terraform-null-label.git?ref={{ .Version }}
```

is automatically resolved as:

```
git::https://github.com/cloudposse/terraform-null-label.git?depth=1&ref={{ .Version }}
```

## Authentication & Token Usage for HTTPS

Atmos prioritizes authentication credentials based on predefined environment variables. The priority order for each provider is:

### GitHub

- **`ATMOS_GITHUB_TOKEN`**
  Bearer token for GitHub API requests, enabling authentication for private repositories and higher rate limits.
- **`GITHUB_TOKEN`**
  Used as a fallback if 
  `ATMOS_GITHUB_TOKEN`
   is not set.

**Default Username for HTTPS:** `x-access-token`

### Bitbucket

- **`ATMOS_BITBUCKET_TOKEN`**
  Bitbucket app password for API requests; used to avoid rate limits. When both 
  `ATMOS_BITBUCKET_TOKEN`
   and 
  `BITBUCKET_TOKEN`
   are defined, the former prevails.
- **`BITBUCKET_TOKEN`**
  Used as a fallback when 
  `ATMOS_BITBUCKET_TOKEN`
   is not set.
- **`BITBUCKET_USERNAME`**
  Bitbucket username for authentication. Bitbucket requires a valid username and does not accept dummy values like 
  `x-access-token`
  .

### GitLab

- **`ATMOS_GITLAB_TOKEN`**
  Personal Access Token (PAT) for GitLab authentication. Takes precedence over 
  `GITLAB_TOKEN`
  .
- **`GITLAB_TOKEN`**
  Used as a fallback if 
  `ATMOS_GITLAB_TOKEN`
   is not set.

**Default Username for HTTPS:** `"oauth2"`

## How HTTPS URLs Are Resolved

When resolving Git sources, Atmos follows these rules:

1. If a **full HTTPS URL** is provided (`git::https://github.com/...`), it is used as-is. No token data is injected, even if environment variables are set.
2. If a **repository name** is provided without a scheme (`github.com/org/repo.git`), it defaults to `https://`, and if a token is set, it is injected into the URL.
3. If a **username and repository name** are provided in SCP format (`git@github.com:org/repo.git`), it is rewritten as an SSH URL.

:::note
For more details on configuration, refer to [Atmos Configuration](/cli/configuration).

:::

:::tip
Run `atmos vendor pull --help` to see all the available options
:::

## Examples

### Pull Everything

```shell
# Pull all vendored components
atmos vendor pull

# Explicit flag form
atmos vendor pull --everything
```

### Pull by Tags

Use tags to selectively vendor groups of components. Tags are defined in your `vendor.yaml` and allow you to organize components by purpose, team, or environment:

```shell
# Pull only networking-related components
atmos vendor pull --tags networking

# Pull components for development environment
atmos vendor pull --tags dev

# Pull multiple tag groups
atmos vendor pull --tags dev,test

# Preview what would be pulled (dry-run)
atmos vendor pull --tags networking --dry-run
```

### Pull Specific Components

```shell
# Pull a specific component by name
atmos vendor pull --component vpc
atmos vendor pull -c vpc

# Pull multiple components
atmos vendor pull -c vpc-flow-logs-bucket

# Pull a Helmfile component
atmos vendor pull -c echo-server --type helmfile
```

:::note

When executing the `atmos vendor pull` command, Atmos performs the following steps to decide which vendoring manifest to use:

- If `vendor.yaml` manifest is found (in the directory from which the command is executed), Atmos will parse the file and execute the command
  against it. If the flag `--component` is not specified, Atmos will vendor all the artifacts defined in the `vendor.yaml` manifest.
  If the flag `--component` is passed in, Atmos will vendor only that component

- If `vendor.yaml` is not found, Atmos will look for the `component.yaml` manifest in the component's folder. If `component.yaml` is not found,
  an error will be thrown. The flag `--component` is required in this case

:::

## Flags

- **`--component` / `-c` (optional)**
  Atmos component to pull.
- **`--everything` (optional)**
  Vendor all components.
- **`--tags` (optional)**
  Only vendor the components that have the specified tags.
  `tags`
   is a comma-separated values (CSV) string.
- **`--type` / `-t` (optional)**
  Component type: 
  `terraform`
   or 
  `helmfile`
   (
  `terraform`
   is default).
- **`--dry-run` (optional)**
  Dry run.