Tutorial: Import Your First Dataset

This tutorial walks you through importing your first dataset into Flywheel using the CLI, from installation to verification. You'll learn the complete workflow and gain confidence using the CLI.

Time to complete: 20-30 minutes

What you'll learn:

• Install and set up the Flywheel CLI
• Authenticate with your Flywheel site
• Prepare DICOM data for import
• Run your first import command
• Verify the import was successful
• View your data in Flywheel

Prerequisites

Before starting this tutorial, ensure you have:

• Flywheel account with access to your organization's Flywheel site
• Permissions to upload data to at least one group
• Sample DICOM data (10-20 files recommended for this tutorial)
  • If you don't have DICOM data, you can download sample datasets from public repositories
• Basic command line knowledge (navigating directories, running commands)
  • New to command line? See Codecademy's Command Line Introduction

Step 1: Install the Flywheel CLI

Download the CLI

1. Log in to your Flywheel site in a web browser
2. Click your profile icon in the upper-right corner
3. Select Profile
4. Scroll to the Download Flywheel CLI section
5. Click the download link for your operating system (Windows, macOS, or Linux)

A zip file will download to your computer.

Extract and Locate the CLI

Windows:

1. Double-click the downloaded zip file to extract it
2. Find the fw.exe file inside
3. Note the location (e.g., C:\Users\YourName\Downloads\windows_amd64)

macOS:

1. Double-click the downloaded zip file to extract it
2. Find the fw application
3. If using macOS 10.15 Catalina or later:
4. Right-click on fw and select Open
5. Click Open in the security warning
6. Note the location (e.g., ~/Downloads/darwin_amd64)

Linux:

1. Extract the zip file: unzip fw-linux_amd64.zip
2. Find the fw executable
3. Note the location (e.g., ~/Downloads/linux_amd64)

Test the CLI

Open Terminal (Mac/Linux) or Command Prompt (Windows) and navigate to the CLI location:

1
2
3
4
5

# Mac/Linux example
cd ~/Downloads/darwin_amd64

# Windows example
cd C:\Users\YourName\Downloads\windows_amd64

Run the version command to verify the CLI works:

1
2
3
4
5

# Mac/Linux
./fw version

# Windows
fw.exe version

You should see output like:

1
2

flywheel-cli
  version: 20.3.1

Success! The CLI is installed and working.

Step 2: Get Your API Key

The API key allows the CLI to authenticate with your Flywheel site.

1. In your web browser, go back to your Flywheel Profile page
2. Scroll to the API Keys section
3. Click Generate API Key
4. Copy the generated key (you'll need this in the next step)

Step 3: Login to Flywheel

In your terminal, run the login command with your API key:

1
2
3
4
5

# Mac/Linux
./fw login YOUR_API_KEY_HERE

# Windows
fw.exe login YOUR_API_KEY_HERE

Replace YOUR_API_KEY_HERE with the API key you copied.

Expected output:

1

You are now logged in as Your Name!

Verify Authentication

Check your login status:

1
2
3
4
5

# Mac/Linux
./fw status

# Windows
fw.exe status

Expected output:

1

You are currently logged in to https://your-site.flywheel.io as your.email@example.com

Success! You're now authenticated.

Step 4: Prepare Your Data

For this tutorial, we'll use DICOM files. Let's organize and inspect them.

Organize Your DICOM Files

1. Create a folder for this tutorial:

1

mkdir ~/flywheel-tutorial

1. Copy your sample DICOM files into this folder:

1
2

# Example - adjust path to your DICOM files
cp /path/to/your/dicom/files/*.dcm ~/flywheel-tutorial/

1. Verify the files are there:

1

ls ~/flywheel-tutorial/

You should see your DICOM files listed.

Check DICOM File Extensions

The CLI looks for specific DICOM file extensions. Verify your files have one of these:

• .dcm
• .dcm.gz
• .dicom
• .dicom.gz
• .ima
• .ima.gz

If your DICOM files have no extension or a different extension, you'll need to use the --force-scan flag later.

Step 5: Find Your Target Group and Project

You need to know where in Flywheel you want to import the data.

List Available Groups

1
2
3
4
5

# Mac/Linux
./fw ls

# Windows
fw.exe ls

Example output:

1
2
3

admin    psychology
read     neuroscience
write    cardiology

This shows your permission level and group names. Choose a group where you have admin or write permissions.

List Projects in a Group

Let's say you chose the psychology group:

1
2
3
4
5

# Mac/Linux
./fw ls psychology

# Windows
fw.exe ls psychology

Example output:

1
2
3

admin    AnxietyStudy
admin    MemoryResearch
write    CognitiveLoad

You can either:

• Use an existing project (e.g., AnxietyStudy)
• Let the CLI create a new project during import

For this tutorial, we'll create a new project called TutorialImport.

Step 6: Run Your First Import

Now for the exciting part - importing your data!

The Import Command

We'll use fw ingest dicom to import DICOM files. Here's the basic structure:

1

fw ingest dicom [options] <source_folder> <group_id> <project_label>

Execute the Import

Run this command (adjust paths and names as needed):

1
2
3
4
5

# Mac/Linux
./fw ingest dicom ~/flywheel-tutorial psychology TutorialImport

# Windows
fw.exe ingest dicom C:\Users\YourName\flywheel-tutorial psychology TutorialImport

What Happens Next

1. Scanning: The CLI scans your DICOM files and reads metadata
2. Hierarchy Preview: You'll see how the CLI plans to organize the data:

1
2
3
4
5

Group: psychology
Project: TutorialImport
Subject: sub-001 (from PatientID in DICOM)
Session: ses-01 (from StudyDescription in DICOM)
Acquisition: T1w (from SeriesDescription in DICOM)

1. Confirmation Prompt: The CLI asks you to confirm:

1
2

Import 15 files into psychology/TutorialImport?
Continue? (yes/no):

1. Type yes and press Enter

2. Upload Progress: You'll see progress as files upload:

1
2

Uploading files: [████████████████████] 100%
Import complete: 15 files uploaded successfully

Congratulations! You just imported your first dataset.

Step 7: Verify the Import

Let's confirm everything worked correctly.

Check with the CLI

List the contents of your new project:

1
2
3
4
5

# Mac/Linux
./fw ls psychology/TutorialImport

# Windows
fw.exe ls psychology/TutorialImport

Expected output:

1

admin    sub-001

Look deeper to see sessions:

1
2
3
4
5

# Mac/Linux
./fw ls psychology/TutorialImport/sub-001

# Windows
fw.exe ls psychology/TutorialImport/sub-001

Expected output:

1

admin    ses-01

Check in the Web UI

1. Open your Flywheel site in a web browser
2. Navigate to Projects in the left sidebar
3. Filter or search for the TutorialImport project
4. Click on the project to open it
5. You should see:
6. Subject: sub-001
7. Session: ses-01

8. Acquisition with your DICOM files (usually named after SeriesDescription)

9. Click on an acquisition to view:

10. DICOM files (shown as .dicom.zip)
11. Metadata extracted from DICOM headers
12. Preview images (if available)

Success! Your data is in Flywheel and ready for analysis.

Step 8: What's Next?

Now that you've completed your first import, here's what you can do:

Explore Your Data

• Browse the hierarchy: Use fw ls to explore your data structure
• Download files: Try fw download psychology/TutorialImport/sub-001
• View metadata: Check the web UI to see what metadata was extracted

Import More Data

• Import additional subjects: Run the import command again with different data
• Use advanced options:
  • --de-identify to remove PHI during import
  • --detect-duplicates to prevent duplicate uploads
  • --verbose to see detailed import progress

Run Analysis

• Configure gear rules: Set up automatic processing for new data
• Run gears manually: Process your data with Flywheel gears
• Export results: Download processed data for further analysis

Learn More

• DICOM Import Reference - Full command options
• BIDS Import Guide - Import BIDS datasets
• Template Import Guide - Handle non-standard folder structures
• CLI Examples - More CLI usage examples

Troubleshooting

"No DICOM files found"

Problem: The CLI can't find any DICOM files.

Solution:

• Verify files have correct extensions (.dcm, .dicom, etc.)
• Try adding --force-scan flag to scan all files
• Check the source path is correct

"Permission denied: Cannot create project"

Problem: You don't have permissions to create projects in the group.

Solution:

• Use an existing project instead of creating a new one
• Contact your Flywheel administrator to grant you permissions
• Try a different group where you have admin permissions

"Invalid DICOM - missing UID tag"

Problem: DICOM files are missing required metadata tags.

Solution:

• Verify files are valid DICOM using a DICOM viewer
• Check if files were properly exported from imaging equipment
• Try different sample DICOM data for this tutorial

Files uploaded but showing wrong labels

Problem: Subject/session names don't match what you expected.

Solution:

• The CLI uses DICOM tags for labels (PatientID → subject, StudyDescription → session)
• Use --subject and --session flags to override:

1

fw ingest dicom --subject MySubject --session MySession ~/flywheel-tutorial psychology TutorialImport

For more help, see:

• Common DICOM Import Errors
• General Ingest Troubleshooting
• CLI Troubleshooting Guide

Summary

Congratulations on completing your first Flywheel CLI import! You've learned how to:

✅ Install and set up the Flywheel CLI ✅ Authenticate with your Flywheel site ✅ Prepare and organize DICOM data ✅ Run an import command ✅ Verify the import succeeded ✅ View your data in Flywheel

You now have the foundation to import and manage your research data using the Flywheel CLI. Happy importing!