> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.inc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Download files

> Download original media, directories, and projects to your computer, with explicit conflict handling and completion results.

Use `aspect download` to save an ordinary local copy of an asset:

```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage/interview.mov" ./downloads
```

The optional final argument is a **local directory**, not a new filename. It defaults to your current directory. The CLI creates needed local directories and uses the asset's filename.

## Download a folder or project

```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage" ./downloads
aspect download "aspect://Acme/Documentary" ./delivery
```

Folder downloads preserve the directory tree under the selected folder's name. For example, downloading `Footage` to `./downloads` puts its files under `./downloads/Footage/`. The completion message, or the JSON result's `path`, reports the local destination.

These are copies. Changes to downloaded files do not automatically synchronize with Aspect. Use [upload](/docs/cli/uploads) to send a revision back, or [mount the project](/docs/cli/mounts) for a live filesystem workflow.

## Originals, proxies, and previews

The default variant is `original`. Select another representation with `--variant`:

```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage/interview.mov" ./downloads --variant original
aspect download "aspect://Acme/Documentary/Footage/interview.mov" ./proxies --variant stream_proxy
aspect download "aspect://Acme/Documentary/Footage/interview.mov" ./previews --variant preview
```

See [Retrieve proxies and previews](/docs/cli/proxies) for filenames and how missing variants are handled.

## Existing local files

| Option | Behavior |
| - | - |
| No conflict flag | Leave an existing local file in place and skip it. |
| `--replace` | Download a replacement for the existing local file. |
| `--keep-both` | Save another copy with a numeric suffix. |

```bash theme={null}
aspect download "aspect://Acme/Documentary/Deliverables" ./delivery --replace
```

Skipping an existing path does not verify that its contents match the remote file. Use `--replace` when you need to refresh an existing copy. Do not combine the two conflict flags.

## Completion and interruptions

Downloads write to temporary `.part` files and move them into place when complete. Cancelling a running download removes its in-flight temporary files; a completed filename is not left pointing to a partially downloaded file.

Rerunning a download skips existing final files by default. It retries the missing files as a new download rather than continuing a partial file from its previous offset.

For a large delivery, run in the background:

```bash theme={null}
aspect download "aspect://Acme/Documentary/Deliverables" ./delivery --detach
```

Then use [transfer status or wait](/docs/cli/transfers) to confirm completion. With `--json`, the final result contains `downloaded`, `skipped`, `failed`, and the destination `path`. A directory with no files matching the requested variant can complete with zero downloads, so inspect the count if your workflow expects media.