Please read [documentation](https://brainlife.io/docs/cli/install/) on brainlife.io

Copyright The University of Texas at Austin

---

## S3 File Browser & Download

Some Brainlife projects store raw files directly in S3 rather than as typed data objects. These commands let you browse and download those files from the CLI.

You must be logged in (`bl login`) and have owner, admin, or member access to the project.

---

### Listing files (`bl data query --s3`)

Browse the files and folders stored under a project's S3 prefix.

```bash
# List top-level folders/files in a project
bl data query --project <projectid> --s3

# Browse into a subfolder (trailing slash required)
bl data query --project <projectid> --s3 --path ROOT/

# Go deeper into a nested folder
bl data query --project <projectid> --s3 --path ROOT/Raw_metascientific_data/

# Output as JSON (useful for scripting)
bl data query --project <projectid> --s3 --path ROOT/ --json
```

**Example output:**
```
Project: My Research Project (6863bf5c1521e536327bfea7)
Path:    ROOT/

  [DIR]  Raw_metascientific_data/
  [DIR]  Processed/
  [FILE] README.txt (2.1 KB, 3/10/2025)

2 folder(s), 1 file(s)
```

---

### Downloading a single file (`bl data download --project --path`)

```bash
# Download a file to the current directory
bl data download --project <projectid> --path ROOT/Raw_metascientific_data/participants.tsv

# Download a file to a specific local directory
bl data download --project <projectid> --path ROOT/Raw_metascientific_data/participants.tsv -d ./my-data
```

---

### Downloading a folder (`bl data download --project --path <folder/>`)

A trailing `/` on `--path` tells the CLI to download the entire folder as a tar archive. Directory structure is preserved locally.

```bash
# Download a folder (creates ./Raw_metascientific_data/ in the current directory)
bl data download --project <projectid> --path ROOT/Raw_metascientific_data/

# Download a folder to a specific output directory
bl data download --project <projectid> --path ROOT/ -d ./project-data
```

---

### Notes

- `--project` accepts either a project ID or a project name.
- A trailing `/` on `--path` means "download this folder". Without it, the CLI treats the path as a single file.
- These commands only work for projects whose storage type is S3. Other projects will return an error.