Skip to content

File Management Commands

The Flywheel CLI provides four commands for browsing and managing individual files: fw ls, fw cp, fw upload, and fw download. These commands mirror standard terminal file system commands, making it easy to work with data on Flywheel.

Single-File Operations

These commands are designed for working with individual files or containers. For bulk operations involving many files, see:

The fw ls Command

Browse the Flywheel hierarchy using fw ls, similar to the standard ls command for listing directories.

Usage

1
fw ls [path]

Arguments

Argument Required Description
path No The Flywheel path to list (e.g., group/project/subject). If omitted, lists all groups.

Optional Arguments

Optional Argument Description
--ids Display database identifiers for each container
-a, --all Show all containers and files
Optional Argument Description
-h, --help Show help message and exit.
-C PATH, --config-file Specify configuration options via config file.*
--no-config Do NOT load the default configuration file.
-y, --yes Assume the answer is yes to all prompts.
--ca-certs CA_CERTS Path to a local Certificate Authority certificate bundle file. This option may be required when using a private Certificate Authority.
--timezone TIMEZONE Set the effective local timezone to use when uploading data.
-q, --quiet Squelch log messages to the console.
-d, --debug Turn on debug logging.
-v, --verbose Get more detailed output.

* Learn more about how to create this file.

Examples

List all groups

1
fw ls

Output:

1
2
3
admin    psychology
read     neuroscience
write    cardiology

The output shows permission level followed by group name.

List projects in a group

1
fw ls psychology

Output:

1
2
3
admin    AnxietyStudy
read     MemoryResearch
write    CognitiveLoad

List subjects in a project

1
fw ls psychology/AnxietyStudy

Output:

1
2
3
admin    sub-001
admin    sub-002
admin    sub-003

1
2
3
4
5
6
7
8
# List sessions for a subject
fw ls psychology/AnxietyStudy/sub-001

# List acquisitions for a session
fw ls psychology/AnxietyStudy/sub-001/ses-01

# List files in an acquisition
fw ls psychology/AnxietyStudy/sub-001/ses-01/anat

Show database IDs

1
fw ls --ids psychology/AnxietyStudy

This displays the internal Flywheel database ID alongside each container name, useful for API operations.

Understanding the Hierarchy

Flywheel organizes data in a hierarchical structure:

1
2
3
4
5
6
Group
└── Project
    └── Subject
        └── Session
            └── Acquisition
                └── Files

Use fw ls to navigate each level, just like navigating directories on your local filesystem.

Handling Spaces in Names

If a container name includes spaces, use quotes:

1
fw ls "psychology/My Research Project"

The fw cp Command

Copy files between your local filesystem and Flywheel, or between Flywheel locations, using fw cp.

Usage

1
fw cp <source> <destination>

Required Arguments

Required Argument Description
source The source path (local file or Flywheel path using fw://)
destination The destination path (local file or Flywheel path using fw://)

Optional Arguments

Optional Argument Description
-h, --help Show help message and exit.
-C PATH, --config-file Specify configuration options via config file.*
--no-config Do NOT load the default configuration file.
-y, --yes Assume the answer is yes to all prompts.
--ca-certs CA_CERTS Path to a local Certificate Authority certificate bundle file. This option may be required when using a private Certificate Authority.
--timezone TIMEZONE Set the effective local timezone to use when uploading data.
-q, --quiet Squelch log messages to the console.
-d, --debug Turn on debug logging.
-v, --verbose Get more detailed output.

* Learn more about how to create this file.

Flywheel Path Format

Use the fw:// prefix to specify Flywheel paths:

1
fw://group/project/subject/session/acquisition/filename

Examples

Copy from local to Flywheel

1
fw cp /path/to/local/file.txt fw://psychology/AnxietyStudy/sub-001/ses-01/anat/notes.txt

Copy from Flywheel to local

1
fw cp fw://psychology/AnxietyStudy/sub-001/ses-01/anat/scan.nii.gz /path/to/local/scan.nii.gz

Copy between Flywheel containers

1
fw cp fw://psychology/Study1/sub-001/ses-01/anat/data.nii fw://psychology/Study2/sub-001/ses-01/anat/data.nii

When to Use fw cp

  • Copying a single file to or from Flywheel
  • Moving files between Flywheel containers
  • Quick file transfers without downloading entire containers

Comparison: fw cp vs. Other Commands

Task Use This Command
Copy single file fw cp
Upload single file to container fw upload (simpler syntax)
Download single file fw cp or fw download
Download entire container fw download
Upload many files fw ingest

The fw upload Command

Upload a single local file to a specific Flywheel container using fw upload.

Usage

1
fw upload <local-file> <destination-path>

Required Arguments

Required Argument Description
local-file Path to the local file to upload
destination-path Flywheel container path: group/project/subject/session/acquisition

Optional Arguments

Optional Argument Description
-h, --help Show help message and exit.
-C PATH, --config-file Specify configuration options via config file.*
--no-config Do NOT load the default configuration file.
-y, --yes Assume the answer is yes to all prompts.
--ca-certs CA_CERTS Path to a local Certificate Authority certificate bundle file. This option may be required when using a private Certificate Authority.
--timezone TIMEZONE Set the effective local timezone to use when uploading data.
-q, --quiet Squelch log messages to the console.
-d, --debug Turn on debug logging.
-v, --verbose Get more detailed output.

* Learn more about how to create this file.

Examples

Upload file to acquisition

1
fw upload /path/to/data.nii.gz psychology/AnxietyStudy/sub-001/ses-01/anat

Upload file to session

1
fw upload /path/to/notes.txt psychology/AnxietyStudy/sub-001/ses-01

Upload file to project

1
fw upload /path/to/protocol.pdf psychology/AnxietyStudy

Where Files Are Stored

Files uploaded to different container levels are stored in different locations:

  • Project: Stored as project attachments
  • Subject: Stored as subject attachments
  • Session: Stored as session attachments
  • Acquisition: Stored as acquisition files

When to Use fw upload

  • Uploading a single file to an existing container
  • Adding documentation or metadata files
  • Quick uploads without complex folder structures

Note

For uploading multiple files or entire datasets, use fw ingest commands instead.

The fw download Command

Download files or entire containers from Flywheel to your local filesystem using fw download.

Usage

1
fw download [options] <source-path>

Required Arguments

Required Argument Description
source-path The Flywheel path to download (e.g., group/project/subject/session/acquisition or specific file path)

Optional Arguments

Download Options

Optional Argument Description
-i FILE_TYPE, --include FILE_TYPE Download only files with the specified types.*
-e FILE_TYPE, --exclude FILE_TYPE Ignore files with the specified types.*
-o, --output file name Name of the folder where the data is downloaded
-p PREFIX, --prefix PREFIX Prefix for downloaded directory structure

* Learn more about file types in Flywheel

General Options

Optional Argument Description
-h, --help Show help message and exit.
-C PATH, --config-file Specify configuration options via config file.*
--no-config Do NOT load the default configuration file.
-y, --yes Assume the answer is yes to all prompts.
--ca-certs CA_CERTS Path to a local Certificate Authority certificate bundle file. This option may be required when using a private Certificate Authority.
--timezone TIMEZONE Set the effective local timezone to use when uploading data.
-q, --quiet Squelch log messages to the console.
-d, --debug Turn on debug logging.
-v, --verbose Get more detailed output.

* Learn more about how to create this file.

Examples

Download an entire subject

1
fw download psychology/AnxietyStudy/sub-001

Output:

1
2
3
4
This download will be about 218 MB comprising 39 files.

Continue? (yes/no): yes
Wrote 218 MB to sub-001.tar

Download a specific session

1
fw download psychology/AnxietyStudy/sub-001/ses-01

Download a single acquisition

1
fw download psychology/AnxietyStudy/sub-001/ses-01/anat

Download specific file types only

1
2
3
4
5
# Download only DICOM files
fw download --include dicom psychology/AnxietyStudy/sub-001

# Download everything except DICOM files
fw download --exclude dicom psychology/AnxietyStudy/sub-001

Download to specific output location

1
fw download -o /path/to/output psychology/AnxietyStudy/sub-001

Download with custom prefix

1
fw download -p MyStudy psychology/AnxietyStudy/sub-001

This creates a directory structure like: MyStudy/AnxietyStudy/sub-001/...

Understanding Download Structure

When you download a container, fw download creates a .tar archive by default containing:

  • All files in the container
  • Metadata about the container
  • The complete hierarchy below that container

To extract the downloaded archive:

1
tar -xvf sub-001.tar

When to Use fw download

  • Downloading data for local analysis
  • Creating backups of specific subjects or sessions
  • Retrieving processed results from Flywheel
  • Downloading specific file types from a container

Note

For exporting data in specific formats (like BIDS), use fw export bids instead.

Common Workflows

Explore and Download Data

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 1. List available groups
fw ls

# 2. Browse projects
fw ls psychology

# 3. Check what's in a project
fw ls psychology/AnxietyStudy

# 4. Download a subject's data
fw download psychology/AnxietyStudy/sub-001

Upload Analysis Results

1
2
3
4
5
# 1. Find the target container
fw ls psychology/AnxietyStudy/sub-001/ses-01

# 2. Upload your results file
fw upload /path/to/analysis-results.csv psychology/AnxietyStudy/sub-001/ses-01

Copy File Between Projects

1
2
3
4
5
6
# 1. List source location
fw ls sourcegroup/sourceproject/sub-001/ses-01/anat

# 2. Copy file to destination
fw cp fw://sourcegroup/sourceproject/sub-001/ses-01/anat/template.nii.gz \
     fw://destgroup/destproject/sub-001/ses-01/anat/template.nii.gz

Selective Download

1
2
3
4
5
# Download only NIfTI files from a session
fw download --include nifti psychology/AnxietyStudy/sub-001/ses-01

# Download everything except raw DICOM files
fw download --exclude dicom psychology/AnxietyStudy/sub-001/ses-01

Command Comparison

When to Use Each Command

Task Best Command Why
Browse Flywheel hierarchy fw ls Quick navigation, see what's available
Copy single file to Flywheel fw upload or fw cp upload is simpler, cp supports fw:// syntax
Copy single file from Flywheel fw cp or fw download cp for single files, download for containers
Download entire container fw download Automatically creates archive with all files
Copy between Flywheel locations fw cp Direct copy without downloading first
Upload many files fw ingest See Ingest Commands
Download in BIDS format fw export bids See Export Commands

Syntax Comparison

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# List
fw ls group/project/subject

# Copy (local to Flywheel)
fw cp /local/file.txt fw://group/project/subject/session/acquisition/file.txt

# Upload (local to Flywheel)
fw upload /local/file.txt group/project/subject/session/acquisition

# Download (Flywheel to local)
fw download group/project/subject/session/acquisition

# Copy (Flywheel to Flywheel)
fw cp fw://source/path fw://dest/path

Common Errors

Common CLI Errors

For authentication, network issues, and other errors common to all CLI commands, see the CLI Troubleshooting Guide.

"Path not found"

Cause: The specified Flywheel path doesn't exist or you don't have access.

Solution:

  • Use fw ls to verify the path exists
  • Check spelling and capitalization (paths are case-sensitive)
  • Verify you have permission to access the container

"Permission denied"

Cause: You don't have sufficient permissions for the operation.

Solution:

  • Check your permission level with fw ls
  • Contact your Flywheel site administrator to request access
  • Verify you're logged in with fw status

"File already exists"

Cause: When using fw upload or fw cp, a file with the same name already exists at the destination.

Solution:

  • Rename your local file before uploading
  • Delete the existing file in Flywheel first (if appropriate)
  • Use a different destination path

"Connection timeout"

Cause: Large file transfers may timeout on slow connections.

Solution:

  • For large files, use fw ingest commands which are optimized for bulk transfers
  • Check your network connection
  • Try again during off-peak hours