Skip to content

Importing a Structured Folder of Imaging Data with the CLI

Introduction

The folder command should be used if you are importing data that you previously downloaded from Flywheel, or if you are importing data that was shared from another Flywheel site.

This article explains how to use the ingest folder command.

The folder command requires your directory of data to exactly match the the Flywheel hierarchy. Below is the basic Flywheel hierarchy:

folderImport-update.png

Strict Folder Structure

If the directory you are importing does not exactly match the directory shown in the image above, consider using another method to import your images. For example, if all of your images are DICOMs, consider using our dicom importer to automatically determine containers in Flywheel for your data.

This option also groups images by subjects and sessions. Learn about the other ways to import data.

Prerequisites

  1. Follow these instructions to download and install the Flywheel CLI. If you cannot download the Flywheel CLI to your computer, you can upload smaller batches of files using your web browser.

Unsupported File Types

The ingest folder command does not support uploading site, group, or project de-ID profiles.

Use one of these supported methods if you are uploading site, group, or project de-ID profiles.

Before You Begin

Ensure you have:

CLI Setup:

  • Flywheel CLI installed on your computer
  • Valid API key and authenticated CLI - verify with fw status
  • Stable internet connection for data upload

Permissions:

You need the following project-level permissions in the target group/project:

  • Single File Upload/Create or Bulk File Upload - Required for CLI ingest commands
  • Create Container - Required if creating new subjects, sessions, or acquisitions

To check your permissions, navigate to the project in the web UI and check your role. Learn more about user roles and permissions.

Data Requirements:

  • Folder structure must match Flywheel hierarchy exactly:
    • Group → Project → Subject → Session → Acquisition → Files
  • Each level must be present as a folder or specified with command flags (e.g., --group, --project)
  • DICOM files should be unzipped (use --dicom flag to process and zip DICOM folders during ingest)

Important Notes:

  • If your folder structure doesn't match Flywheel hierarchy, consider using dicom ingest or template ingest instead
  • Use --no-subjects flag if you have sessions but no subject-level folders
  • Use --no-sessions flag if you have subjects but no session-level folders

For PHI/Sensitive Data:

If your DICOM files contain Protected Health Information (PHI), configure de-identification before upload:

For Automated Processing (Optional):

To automatically process data as it arrives, set up gear rules before uploading:

  • Configure gear rules to run analysis automatically on new data
  • Test rules on a small dataset first to verify they work as expected

Instruction Steps

Steps for Ingest Folder

  1. Open Terminal.
  2. Note the location of the parent folder for your data.
  3. If your DICOM images are in a .zip file, unzip them.

  4. Enter the ingest folder command:

    fw ingest folder <optional flags> --group <groupid> --project <projectlabel> --dicom <folder with images> <SRC>

    For example: fw ingest folder --group psychology --project MyProject --dicom dcm001 ~/Desktop/MultiCenterStudy

    • The --group and --project flags designate where in Flywheel the data should be imported. This overwrites whatever the name of the folder is in the directory you are uploading.
    • The --dicom flag takes subfolders with DICOM images, analyzes them, zips them, and adds them as acquisitions. The --dicom flag is required if you have enabled project, group, or site de-ID profiles for de-identification.

  5. Review the hierarchy and scan summary to make sure it matches what you expect.

  6. Enter yes to begin ingesting.

    The Flywheel CLI displays its ingest progress

  7. Sign in to Flywheel to view your data.

Verify Success

After the ingest completes, verify your data was imported correctly:

1. Check the CLI Output

Look for confirmation messages in the terminal:

  • Number of files processed
  • Containers created or updated (subjects, sessions, acquisitions)
  • Upload completion status

2. View Data in Flywheel Web UI

  1. Sign in to your Flywheel site
  2. Navigate to your project: Groups → [Your Group] → [Your Project]
  3. Verify:
  4. Folder hierarchy was preserved in Flywheel structure
  5. Subjects match your folder names
  6. Sessions exist under each subject
  7. Acquisitions contain the expected files
  8. File counts match what you uploaded

3. Check File Organization

Click on acquisitions to verify:

  • Files are in the correct containers
  • File types are set correctly
  • DICOM files were processed and zipped (if --dicom flag was used)
  • Metadata was preserved

Next Steps

After successfully importing your folder data:

Troubleshooting

Each level in the Flywheel hierarchy must be specified during ingest. This means you must either:

  • Have a folder for each container (Group, Project, Subject, Session, Acquisitions, and images), or
  • Manually configure the container using an optional flag. For example: --group <groupID> or --project <project label>.

For more information about the optional flags, see our reference guide.