# 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.

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.