The fw export bids Command

If you have a project that follows the Brain Imaging Data Structure (BIDS) format, you can use the CLI to download the project so it stays in the BIDS format.

Prerequisites

It is required that your project is already in the BIDS format to use the export bids command. If your project is not yet in BIDS format, see our resources for help transitioning to BIDS. This also includes running the BIDS curation gear on your project.

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 download

Permissions:

You need the following project-level permissions:

• Download File - Required to download files from the project
• View Metadata - Required to access BIDS metadata and structure

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

Project Requirements:

• Project must be BIDS-curated (run BIDS curation gear first)
• Verify BIDS structure in Flywheel web UI (look for BIDS icons and metadata)
• Project should follow BIDS specification

Local System:

• Sufficient disk space at destination for exported data
• Write permissions for the destination directory
• Destination directory exists or you can create it

Usage

fw export bids [Project in Flywheel] [Destination folder] [optional flags]

Required Arguments

Optional Arguments

Export Bids

General

* Learn more about how to create this file.

Examples

fw export bids -p "Project Name" [Destination folder]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$ fw export bids -p "Anxiety Study" ~/Documents/FlywheelData
INFO: Verify download directory exists
INFO: Processing project files
INFO: Processing session files
INFO: Processing acquisition files
INFO: Downloading project files
INFO: Downloading session files
INFO: Downloading acquisition files
INFO: Downloading acquisition file: sub-13_inplaneT2.nii.gz
...

Your data is downloaded to your computer, and your project maintains its BIDS format.

Verify Success

After the export completes, verify your BIDS data was exported correctly:

1. Check the CLI Output

Look for confirmation messages in the terminal:

• "INFO: Processing [project/session/acquisition] files"
• "INFO: Downloading [type] files"
• Completion message with file counts

2. Verify Local BIDS Structure

Navigate to your destination directory and check:

1

ls -la ~/Documents/FlywheelData

Verify the BIDS directory structure:

• dataset_description.json exists in root
• Subject folders follow sub-<label> naming
• Session folders follow ses-<label> naming (if applicable)
• Data organized by modality (anat, func, dwi, etc.)
• Sidecar JSON files accompany imaging data

3. Validate BIDS Compliance

Use the BIDS validator to check exported data:

1
2
3
4
5

# Online validator
# Visit: https://bids-standard.github.io/bids-validator/

# Or use command-line validator
bids-validator ~/Documents/FlywheelData

4. Check File Counts

Compare file counts between Flywheel and exported data:

• Number of subjects matches
• Number of sessions per subject matches
• File counts per acquisition match
• All expected data types are present

5. Verify Metadata Preservation

Open a sidecar JSON file and verify:

• BIDS metadata fields are present
• Values match what's in Flywheel
• Required BIDS fields exist (e.g., RepetitionTime for functional data)

Next Steps

After successfully exporting your BIDS data:

• Run BIDS analysis tools: Use exported data with BIDS-compatible pipelines (fMRIPrep, QSIPrep, MRIQC, etc.)
• Share data: BIDS format makes it easy to share with collaborators or deposit in repositories
• Re-import if needed: You can re-import BIDS data to Flywheel using fw ingest bids

Common Errors

"Project not found"

Cause: The specified project does not exist or you don't have access to it.

Solution:

• Verify the project label is spelled correctly (case-sensitive)
• Check you have read permissions on the project
• Use fw ls <group> to see available projects
• Ensure you're logged into the correct Flywheel site with fw status

"Project is not BIDS-curated"

Cause: The project has not been curated into BIDS format using the BIDS curation gear.

Solution:

• Run the BIDS curation gear on your project first
• Verify BIDS metadata exists by checking for BIDS icons in the Flywheel UI
• Ensure your data follows the BIDS specification

"Permission denied" writing to destination

Cause: You don't have write permissions for the destination directory.

Solution:

• Choose a destination directory where you have write permissions
• Create the directory first: mkdir -p /path/to/destination
• Check directory permissions: ls -la /path/to/parent/
• Use a different destination path in your home directory

Export fails with generic error

Cause: Various issues during export (corrupted files, incomplete BIDS structure, network issues).

Solution:

• Check the detailed error message in the CLI output
• Verify project has complete BIDS metadata
• Try exporting a single subject first: --subject sub-01
• Check CLI logs for detailed error information
• Ensure sufficient disk space is available at the destination

See Also

Related Commands:

• Import BIDS Data - Import neuroimaging data in BIDS format
• Sync to Storage - Download large datasets with folder structure
• Download Files - Download individual files or containers

BIDS Resources:

• BIDS Specification - Official BIDS format documentation
• BIDS Validator - Validate exported BIDS datasets
• BIDS Curation - Curate data into BIDS format

Troubleshooting:

• CLI Troubleshooting Guide - Common CLI issues and solutions
• Finding CLI Logs - Locate detailed error logs