Skip to content

Flywheel CLI Command Cheat Sheet

Quick reference for the most common Flywheel CLI commands. For detailed documentation, click the command name.

Getting Help

Run any command with -h or --help to see detailed usage information:

1
fw <command> --help

Setup and Authentication

Command Syntax Description
version fw version Display CLI version
login fw login <api_key> Authenticate with Flywheel
status fw status Check current login status
logout fw logout Delete saved API key

Browse and Navigate

Command Syntax Description
ls fw ls [path] List groups, projects, or containers
fw ls List all accessible groups
fw ls <group> List projects in a group
fw ls <group>/<project> List subjects in a project

Common Options:

  • --ids - Display database identifiers
  • -a, --all - Show all containers (Site Admin only)

File Operations

Command Syntax Description
download fw download <path> [options] Download files or containers
fw download <path>/<file> Download a single file
fw download <path> --zip Download container as zip
upload fw upload <path> <local_file> Upload file to container
cp fw cp <source> <destination> Copy files between locations

Common Options:

  • -i, --include <type> - Include only specific file types
  • -e, --exclude <type> - Exclude specific file types
  • -o, --output <path> - Specify output location

Import Data (Ingest)

Command Syntax Description Guide
ingest dicom fw ingest dicom <source> <group> <project> Import DICOM files DICOM Import
ingest bids fw ingest bids <folder> <group> Import BIDS dataset BIDS Import
ingest folder fw ingest folder <source> <group> <project> Import structured folder Folder Import
ingest template fw ingest template <folder> <template> Import using custom template Template Guide
ingest project fw ingest project <fw://path> <api_key> Copy project between sites Project Copy

Common Ingest Options:

  • --subject <label> - Override subject label
  • --session <label> - Override session label
  • --de-identify - Apply de-identification during import
  • --deid-profile <name> - Specify de-identification profile
  • --group <id> - Target group ID
  • --project <label> - Target project label

Decision Guide: Which Ingest Command Should I Use?

Export Data

Command Syntax Description Guide
export bids fw export bids -p <project> <destination> Export project in BIDS format BIDS Export
sync fw sync <source> <destination> Sync data to external storage Sync Guide

Common Export Options:

  • --subject <label> - Export single subject
  • --session <label> - Export single session
  • --data-type <type> - Export specific data types
  • --source-data - Include source data (BIDS)
  • -x, --full-project - Include analyses and metadata (sync)
  • --dry-run - Preview without transferring files

De-identification

Command Syntax Description
deid fw deid test <profile> <file> Test de-ID profile on local file
fw deid apply <profile> <file> Apply de-ID profile to local file

Note: The fw deid command is for testing profiles locally. Production de-identification is applied during ingest or via gears.

More Info: De-identification Guide | Create De-ID Profile

Common Flags (All Commands)

Flag Description
-h, --help Show command help
--config-file <file> Use configuration file
-y, --yes Skip confirmation prompts
--debug Enable debug logging
--quiet Suppress log messages
--timezone <tz> Set timezone for imports

Flywheel Path Format

All CLI commands use the fw:// path format to reference containers:

1
2
3
4
5
fw://group/project                           # Project
fw://group/project/subject                   # Subject
fw://group/project/subject/session           # Session
fw://group/project/subject/session/acq       # Acquisition
fw://group/project/subject/session/acq/file  # File

Path with spaces: Use quotes:

1
fw ls "psychology/Anxiety Study"

File Type Filtering

Many commands support filtering by file type:

1
2
3
4
--include dicom              # Only DICOM files
--include nifti              # Only NIfTI files
--exclude dicom              # Everything except DICOM
--include dicom --include nifti  # Multiple types

Common file types: dicom, nifti, pdf, tabular, source code

Learn more about file types

Configuration Files

Simplify complex commands by using configuration files:

1
fw ingest dicom --config-file ingest-config.yaml /data/dicom mygroup myproject

Example config file:

1
2
3
4
subject: sub-01
session: ses-01
de-identify: true
deid-profile: my-profile

Learn more about configuration files

Tips and Best Practices

Performance

  • Use --cluster flag for large imports (if available)
  • Use --dry-run to preview operations before executing
  • Filter by file type to reduce transfer times

Security

  • Store API keys securely (use password managers)
  • Never commit API keys to version control
  • Use cat api-key.txt | xargs fw login to avoid command history

Troubleshooting

  • Add --debug flag to see detailed logs
  • Check fw status to verify authentication
  • Use fw ls to confirm paths before operations

Need help? See the CLI Troubleshooting Guide

See Also

Getting Started:

Command References:

Troubleshooting:

New CLI (Beta):