# atmos aws cloudformation source pull

Use this command to vendor an `aws/cloudformation` component source based on its `source` configuration. This downloads the component from the specified URI and places it in the appropriate component directory.

**Source-Based Version Pinning**

Configure source locations, version pins, and authentication.

Source Configuration[Read more](/stacks/components/aws-cloudformation#source-provisioning)

## Usage

```shell
atmos aws cloudformation source pull <component> --stack <stack> [flags]
```

## Examples

### Basic Usage

Vendor a component source for a specific stack:

```shell
atmos aws cloudformation source pull vpc --stack dev
```

### Force Re-vendor

Re-vendor even if the component directory already exists:

```shell
atmos aws cloudformation source pull vpc --stack dev --force
```

### With Identity Override

Use a specific identity for authentication:

```shell
atmos aws cloudformation source pull vpc --stack dev --identity admin
```

### Preview with `--dry-run`

Use `--dry-run` to check the component, source configuration, and destination without downloading:

```shell
atmos aws cloudformation source pull vpc --stack dev --dry-run
```

## Arguments

- **`component`**
  The name of the Atmos component to vendor. Required for unattended use; when omitted, interactive mode offers component selection if candidates are available.

## Flags

- **`--stack` / `-s`**
  The Atmos stack name, also settable via 
  `ATMOS_STACK`
  . Required for unattended use; when unset, interactive mode offers stack selection if candidates are available.
- **`--force` / `-f`**
  Force re-vendor even if the component directory already exists. Without this flag, the command skips vendoring if the directory exists.
- **`--identity` / `-i`**
  Identity to use for authentication when downloading from protected sources. Overrides the component's default identity.
- **`--dry-run`**
  Validate static configuration and show the destination without authentication,
  downloads, or deletion.

## Description

The command downloads the configured source, applies path filters, and copies
the result to the component's resolved directory. Existing downloads are skipped
unless `--force` is set.

The destination follows the base component, `working_directory`, and workdir
settings. See [Component Directories](/stacks/components/aws-cloudformation#component-directories).

## Configuration

The component must have `source` configured in its stack manifest:

```yaml
components:
  aws/cloudformation:
    vpc:
      source:
        uri: github.com/cloudposse/cloudformation-aws-components//modules/vpc
        version: 1.0.0
        included_paths:
          - "*.yaml"
        excluded_paths:
          - "*.md"
          - "tests/**"
```

## Output

On success:

```text
Vendoring component 'vpc' from source...
Downloading from github.com/cloudposse/cloudformation-aws-components//modules/vpc?ref=1.0.0
✓ Successfully vendored component to components/cloudformation/vpc
```

## See Also

- [Source-Based Version Pinning](/design-patterns/version-management/source-based-versioning) — Design pattern for per-environment version control
- [`atmos aws cloudformation source`](/cli/commands/aws/cloudformation/source) — Parent command overview
- [`atmos aws cloudformation source describe`](/cli/commands/aws/cloudformation/source/describe) — View source configuration
- [`atmos aws cloudformation source list`](/cli/commands/aws/cloudformation/source/list) — List components with source
- [`atmos aws cloudformation source delete`](/cli/commands/aws/cloudformation/source/delete) — Remove vendored source