The Flywheel Command-Line Interface (CLI)

The Command-Line Interface (CLI) provides a powerful way to interact with Flywheel programmatically. Use the CLI to import large datasets, download data, run analyses, and automate workflows.

New CLI (in BETA)

Flywheel is currently building an entirely new CLI, which will eventually replace the legacy CLI.

The new CLI is currently available for all customers as a BETA release for OSX and Linux. The new CLI can be installed alongside the legacy CLI and used independently. When installed, the new CLI is available via the fw-beta command.

The new CLI is the only supported CLI for the following use cases which are not available via the legacy CLI:

Bulk Import
Bulk Export
External Storage Management
Gear Development
Gear Job Management

Refer to the new CLI documentation for more information.

Quick Start

1. Install the CLI

Download and install the Flywheel CLI for your operating system (Windows, macOS, or Linux).

2. Log in

1	`fw login <your_api_key>`

Get your API key from your Flywheel profile page.

3. Verify your connection

1	`fw status`

You should see your username and the Flywheel site you're connected to.

4. Explore your data

fw ls                    # List your groups
fw ls <group>            # List projects in a group
fw ls <group>/<project>  # List subjects in a project

Ready to import data? See Common Tasks below or jump to our Usage Examples.

Common Tasks

Import Data to Flywheel

Choose the right command for your data type:

Data Type	Command	Guide
DICOM files	`fw ingest dicom`	Import DICOM Files
BIDS dataset	`fw ingest bids`	Import BIDS Data
Custom folders	`fw ingest template`	Create a Template
Flywheel exports	`fw ingest folder`	Import Structured Folders

Not sure which to use? Read Which Ingest Command Should I Use?

Download Data from Flywheel

# Download a single file
fw download <group>/<project>/<subject>/<session>/<acquisition>/<filename>

# Download an entire acquisition
fw download <group>/<project>/<subject>/<session>/<acquisition>

# Download with zip compression
fw download --zip <container_path>

Full download documentation

Export Data in Bulk

# Export BIDS format
fw export bids <group>/<project> /local/output/path

# Sync files to external storage
fw sync <source> <destination>

De-identify DICOM Data

# Apply de-identification during ingest
fw ingest dicom /path/to/data --de-identify --deid-profile <profile_name>

De-identification Guide

Get the Flywheel CLI

First time installing? See Installing the Flywheel CLI

Already installed? See Updating the CLI to ensure compatibility with your Flywheel site.

Usage

To view the available list of commands, run fw -h. More information about each command can found in the Command References documentation folder.

> fw -h
Flywheel command-line interface

Usage:
  fw [command]

Available Commands:
  cp          Copy a local file to a remote location, or vice-a-versa
  deid        Create and test de-identification template
  download    Download a remote file or container
  export      Export data from Flywheel
  ingest      Ingest large datasets into Flywheel
  login       Login to a Flywheel instance
  logout      Delete your saved API key
  ls          Show remote files
  status      See your current login status
  sync        Sync files from Flywheel to storage
  upload      Upload a local file to a Flywheel container
  version     Print CLI version

Flags:
  -h, --help   help for fw

Use "fw [command] --help" for more information about a command.

Getting Help

With any command, you can add -h or --help to get more information. For example, with the ls command we'll see in the following section:

usage: fw ls [-h] [--config-file CONFIG_FILE | --no-config] [-y] [--ca-certs CA_CERTS] [--timezone TIMEZONE] [--debug | --quiet]
             [--ids] [-a]
             [path]

positional arguments:
  path                  The path to list subfolders and files

options:
  -h, --help            show this help message and exit
  --config-file CONFIG_FILE, -C 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   The file to use for SSL Certificate Validation
  --timezone TIMEZONE   Set the effective local timezone for imports
  --debug               Turn on debug logging
  --quiet               Squelch log messages to the console
  --ids                 Display database identifiers
  -a, --all             Show all

Learn More

Getting Started

Installation Guide - Download and install the CLI
Usage and Examples - Common CLI commands and workflows
Configuration Files - Simplify complex commands

Authentication

Authentication Commands - Login, logout, and status commands
Check CLI Version - Verify your CLI version

File Management

File Management Commands - Browse and transfer individual files (ls, cp, upload, download)

Data Import

Which Ingest Command Should I Use? - Decision guide
Import DICOM Files - For medical imaging
Import BIDS Data - For neuroimaging datasets
Create an Ingest Template - For custom structures
Copy Projects Between Sites - For multi-site workflows

Data Export

Export to BIDS - Export in BIDS format
Sync to Storage - Sync to external storage

Advanced Topics

De-identify DICOM Files - Apply de-identification profiles
Using Ingest Clusters - Speed up large imports
Troubleshooting - Common issues and solutions

For Developers

Create, test, and upload a gear - Gear development with CLI